{ "openapi": "3.0.3", "info": { "title": "Jsonpage API", "version": "2.0.0", "description": "Company data API. It serves 14 countries (FR, BE, CH, GB, NO, FI, LV, IE, SE, EE, LT, AU, SG, JP) with one format, completes and checks form input (/v2/autocomplete, /v2/validate), verifies EORI customs numbers (/v2/eori), monitors companies (/v2/monitors, /v2/events) and delivers their changes as signed webhooks, described under x-webhooks since OpenAPI 3.0 has no webhooks section.", "x-description-fr": "API de données entreprises à prix fixe. L'API sert 14 pays (France, Belgique, Suisse, Royaume-Uni, Norvège, Finlande, Lettonie, Irlande, Suède, Estonie, Lituanie, Australie, Singapour, Japon) dans un seul format, avec l'autocomplétion et le contrôle de formulaires (/v2/autocomplete, /v2/validate), la surveillance d'entreprises (/v2/monitors, /v2/events) et des webhooks signés (x-webhooks). Authentification : en-tête X-API-Key. Les descriptions sont en anglais ; chaque route porte un résumé en français (x-summary-fr).", "termsOfService": "https://jsonpage.com/cgv", "contact": { "name": "Jsonpage", "url": "https://jsonpage.com/contact" }, "license": { "name": "Proprietary", "url": "https://jsonpage.com/cgv" } }, "servers": [ { "url": "https://api.jsonpage.com/v2", "description": "Production" } ], "security": [ { "ApiKey": [] } ], "externalDocs": { "description": "Documentation (EN) / Documentation (FR)", "url": "https://jsonpage.com/docs" }, "paths": { "/health/live": { "servers": [ { "url": "https://api.jsonpage.com", "description": "Production (service health is served outside /v2)" } ], "get": { "summary": "Liveness check", "x-summary-fr": "Test de disponibilité du service.", "description": "Answers as soon as the service runs. No API key.", "operationId": "healthLive", "security": [], "responses": { "200": { "description": "The service answers", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ok" ] } } }, "example": { "status": "ok" } } } } } } }, "/health/ready": { "servers": [ { "url": "https://api.jsonpage.com", "description": "Production (service health is served outside /v2)" } ], "get": { "summary": "Readiness check", "x-summary-fr": "Test de disponibilité complète du service.", "description": "Tells whether the service is ready to serve data. No API key.", "operationId": "healthReady", "security": [], "responses": { "200": { "description": "Ready", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ready" ] } } }, "example": { "status": "ready" } } } }, "503": { "description": "Not ready", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "data_unavailable", "data_stale" ] } } } } } } } } }, "/health/sources": { "servers": [ { "url": "https://api.jsonpage.com", "description": "Production (service health is served outside /v2)" } ], "get": { "summary": "State of the data", "x-summary-fr": "État des données et date de dernière mise à jour.", "description": "State of the data for each country served (ok, stale or refreshing), as shown on the status page. No API key. It names no provider and gives no date.", "operationId": "healthSources", "security": [], "responses": { "200": { "description": "State of the data of every country served", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ok", "degraded" ] }, "checked_at": { "type": "string", "format": "date-time" }, "sources": { "type": "array", "items": { "type": "object", "properties": { "country": { "type": "string" }, "status": { "type": "string", "enum": [ "ok", "stale", "refreshing" ] } } } } } }, "example": { "status": "ok", "checked_at": "2026-10-03T08:00:00Z", "sources": [ { "country": "FR", "status": "ok" }, { "country": "BE", "status": "ok" }, { "country": "GB", "status": "refreshing" } ] } } } } } } }, "/companies/{id}": { "get": { "summary": "Look up a company by global identifier", "x-summary-fr": "Fiche d'une entreprise à partir de son identifiant global (code pays, tiret, numéro national), avec blocs à la demande : adresse, TVA, signaux, annonces légales, sanctions, établissements.", "description": "Returns the base record, identical in every country, plus the blocks requested with include. France (FR), Belgium (BE), Switzerland (CH), Norway (NO), Finland (FI), Latvia (LV), Ireland (IE), Sweden (SE), Estonia (EE), Lithuania (LT), Australia (AU), Singapore (SG), Japan (JP) and the United Kingdom (GB) are available. Belgian enterprise numbers have 10 digits with a modulo-97 check (BE-0417497106); 0417.497.106, BE0417497106 and the old 9-digit form are accepted. Swiss identifiers are CH- and the 9 digits of the UID without the CHE prefix (CH-101374515 for CHE-101.374.515), whose last digit is a modulo-11 check (eCH-0097); CH-CHE-101.374.515 and CH-CHE-101.374.515 MWST are accepted. In Switzerland, activity and incorporated_on are null (not provided for Switzerland) and closed_on stays null for a closed entity. Norwegian identifiers are NO- and the 9 digits of the organisation number, whose last digit is a modulo-11 check (NO-923609016); 923 609 016 and NO923609016MVA are accepted after the prefix. Finnish identifiers are FI- and the 8 characters of the Business ID without the hyphen, with a modulo-11 check (FI-01120389 for 0112038-9); FI-0112038-9 is accepted. Latvian identifiers are LV- and the 11 digits of the registration number (LV-40003245752), which has no published check digit. In Latvia, activity is null; in Norway and Finland, closed_on stays null for an entity that left the register. Irish identifiers are IE- and the company number without leading zeros (IE-104547), which has no published check digit; the vat block is not available in Ireland. Swedish identifiers are SE- and the 10 digits of the organisation number, whose last digit is a Luhn check (SE-5560427220); 556042-7220, SE5560427220 and SE556042722001 are accepted. In Sweden, the activity code has no label and nace is null. Estonian identifiers are EE- and the 8 digits of the registry code, whose last digit is a check digit (EE-10137025); EE10137025 and the VAT number EE100210460 are accepted. In Estonia, nace is given for EMTAK 2008 codes only. Lithuanian identifiers are LT- and the 9 digits of the legal entity code, whose last digit is a check digit (LT-110053842); LT110053842 (the VAT number) is accepted. In Lithuania, activity is null and the address block is not available. Australian identifiers are AU- and the 11 digits of the ABN (AU-51824753556), with a modulo-89 check; 51 824 753 556 and ABN 51824753556 are accepted. In Australia, activity is null, there is no street address (state and postcode only) and a sole trader is served under its trading name. Singapore identifiers are SG- and the UEN (SG-196800306E for a company, SG-53012345A style for a business, SG-T05LL0003J style for another entity), whose last letter is a check letter; closed_on stays null. In Singapore, activity is the SSIC code and nace is null. Japanese identifiers are JP- and the 13 digits of the corporate number (JP-1180301018771), whose first digit is a check digit. In Japan, names and addresses are in Japanese, activity is null and incorporated_on is null.", "operationId": "getCompanyV2", "parameters": [ { "$ref": "#/components/parameters/CompanyId" }, { "$ref": "#/components/parameters/Include" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/IfNoneMatch" } ], "responses": { "200": { "description": "Company found", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/V2Company" }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "example": { "data": { "id": "FR-552032534", "country": "FR", "registry_id": "552032534", "name": "DANONE", "status": "active", "legal_form": { "code": "5599", "label": "SA a conseil d'administration", "scheme": "FR-CJ" }, "activity": { "nace": "70.10", "code": "70.10Z", "label": "Activites des sieges sociaux", "scheme": "FR-NAF-REV2" }, "incorporated_on": "1955-01-01", "closed_on": null, "updated_at": "2026-10-03T04:00:00Z", "address": { "line": "17 BOULEVARD HAUSSMANN", "postal_code": "75009", "city": "PARIS", "country": "FR", "formatted": "17 BOULEVARD HAUSSMANN 75009 PARIS" }, "vat": { "number": "FR27552032534", "status": "valid", "checked_at": "2026-09-20T10:12:00Z", "source": "EU VAT check" } }, "meta": { "sources": [ { "name": "Official company register: France", "country": "FR", "kind": "register", "data_date": "2026-10-03" } ], "includes": { "address": "ok", "vat": "ok" } } } } } }, "304": { "$ref": "#/components/responses/V2NotModified" }, "400": { "$ref": "#/components/responses/V2BadRequest" }, "401": { "$ref": "#/components/responses/V2Unauthorized" }, "403": { "$ref": "#/components/responses/V2Forbidden" }, "404": { "$ref": "#/components/responses/V2NotFound" }, "429": { "$ref": "#/components/responses/V2TooManyRequests" }, "500": { "$ref": "#/components/responses/V2DataUnavailable" }, "503": { "$ref": "#/components/responses/V2Busy" } }, "x-codeSamples": [ { "lang": "Shell", "label": "curl", "source": "curl -X GET \"https://api.jsonpage.com/v2/companies/FR-552032534\" \\\n -H \"X-API-Key: $JSONPAGE_API_KEY\"" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const res = await fetch(\"https://api.jsonpage.com/v2/companies/FR-552032534\", {\n method: \"GET\",\n headers: { \"X-API-Key\": process.env.JSONPAGE_API_KEY }\n});\nconsole.log(await res.json());" }, { "lang": "Python", "label": "Python", "source": "import os, requests\n\nres = requests.request(\"GET\", \"https://api.jsonpage.com/v2/companies/FR-552032534\",\n headers={\"X-API-Key\": os.environ[\"JSONPAGE_API_KEY\"]})\nprint(res.json())" }, { "lang": "PHP", "label": "PHP", "source": " \"GET\",\n CURLOPT_RETURNTRANSFER => true,\n CURLOPT_HTTPHEADER => [\"X-API-Key: \" . getenv(\"JSONPAGE_API_KEY\")],\n]);\n$data = json_decode(curl_exec($ch), true);" }, { "lang": "Ruby", "label": "Ruby", "source": "require \"net/http\"\nrequire \"json\"\n\nuri = URI(\"https://api.jsonpage.com/v2/companies/FR-552032534\")\nreq = Net::HTTP::Get.new(uri, \"X-API-Key\" => ENV[\"JSONPAGE_API_KEY\"])\nres = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(req) }\nputs JSON.parse(res.body)" } ] } }, "/companies/{id}/establishments": { "get": { "summary": "List the establishments of a company", "x-summary-fr": "Liste des établissements d'une entreprise, page par page.", "description": "Pages through the establishments of a company. Pass the next value of a page as after to get the following page; next is null on the last page. Returns 404 not_available_in_country when the register has no establishments.", "operationId": "listEstablishmentsV2", "parameters": [ { "$ref": "#/components/parameters/CompanyId" }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/After" }, { "$ref": "#/components/parameters/IfNoneMatch" } ], "responses": { "200": { "description": "One page of establishments", "headers": { "ETag": { "$ref": "#/components/headers/ETag" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/EstablishmentPage" }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "example": { "data": { "items": [ { "registry_id": "55203253400646", "name": "DANONE", "head_office": true, "status": "active", "activity": { "nace": "70.10", "code": "70.10Z", "label": "Activites des sieges sociaux", "scheme": "FR-NAF-REV2" }, "opened_on": "2008-01-01", "address": { "line": "17 BOULEVARD HAUSSMANN", "postal_code": "75009", "city": "PARIS", "country": "FR", "formatted": "17 BOULEVARD HAUSSMANN 75009 PARIS" } } ], "next": null }, "meta": { "sources": [ { "name": "Official company register: France", "country": "FR", "kind": "register", "data_date": "2026-10-03" } ] } } } } }, "304": { "$ref": "#/components/responses/V2NotModified" }, "400": { "$ref": "#/components/responses/V2BadRequest" }, "401": { "$ref": "#/components/responses/V2Unauthorized" }, "403": { "$ref": "#/components/responses/V2Forbidden" }, "404": { "$ref": "#/components/responses/V2NotFound" }, "429": { "$ref": "#/components/responses/V2TooManyRequests" }, "500": { "$ref": "#/components/responses/V2DataUnavailable" }, "503": { "$ref": "#/components/responses/V2Busy" } }, "x-codeSamples": [ { "lang": "Shell", "label": "curl", "source": "curl -X GET \"https://api.jsonpage.com/v2/companies/FR-552032534/establishments\" \\\n -H \"X-API-Key: $JSONPAGE_API_KEY\"" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const res = await fetch(\"https://api.jsonpage.com/v2/companies/FR-552032534/establishments\", {\n method: \"GET\",\n headers: { \"X-API-Key\": process.env.JSONPAGE_API_KEY }\n});\nconsole.log(await res.json());" }, { "lang": "Python", "label": "Python", "source": "import os, requests\n\nres = requests.request(\"GET\", \"https://api.jsonpage.com/v2/companies/FR-552032534/establishments\",\n headers={\"X-API-Key\": os.environ[\"JSONPAGE_API_KEY\"]})\nprint(res.json())" }, { "lang": "PHP", "label": "PHP", "source": " \"GET\",\n CURLOPT_RETURNTRANSFER => true,\n CURLOPT_HTTPHEADER => [\"X-API-Key: \" . getenv(\"JSONPAGE_API_KEY\")],\n]);\n$data = json_decode(curl_exec($ch), true);" }, { "lang": "Ruby", "label": "Ruby", "source": "require \"net/http\"\nrequire \"json\"\n\nuri = URI(\"https://api.jsonpage.com/v2/companies/FR-552032534/establishments\")\nreq = Net::HTTP::Get.new(uri, \"X-API-Key\" => ENV[\"JSONPAGE_API_KEY\"])\nres = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(req) }\nputs JSON.parse(res.body)" } ] } }, "/companies": { "get": { "summary": "Search companies by name, or find a registry number in every country served", "x-summary-fr": "Recherche d'entreprises par nom, ou par numéro national dans tous les pays servis.", "description": "Give either q or registry_id; q takes precedence when both are given.\n\nWith q (name search), every word of 2 characters or more must appear in the company name, the last word as a prefix of 3 letters or more (\"dano\" finds DANONE). Case, accents and punctuation are ignored. Results come in this order: exact names first (legal forms such as SA, SAS, SARL, LTD or PLC are ignored when comparing, so \"danone\" finds DANONE first), then active companies, then companies before sole traders, then relevance. Very common words are served without relevance ranking after 400 ms, so that results stay fast. Without country, every country with a name index is searched. Results are base records, as returned by GET /v2/companies/{id}; include is not applied. The whole search counts as one request. Units whose publication is restricted (diffusion status P) have no name and cannot be found by name.\n\nWith registry_id, for clients that only know the national number: lists the companies of every country served that carry this number, usually one; an empty list if none, sorted by identifier.", "operationId": "searchCompaniesV2", "parameters": [ { "$ref": "#/components/parameters/NameQuery" }, { "$ref": "#/components/parameters/SearchCountry" }, { "$ref": "#/components/parameters/SearchStatus" }, { "$ref": "#/components/parameters/SearchLimit" }, { "$ref": "#/components/parameters/RegistryId" }, { "$ref": "#/components/parameters/IfNoneMatch" } ], "responses": { "200": { "description": "Matching companies (name search, best match first; registry_id, sorted by identifier)", "headers": { "ETag": { "$ref": "#/components/headers/ETag" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/V2Company" } }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "example": { "data": [ { "id": "FR-552032534", "country": "FR", "registry_id": "552032534", "name": "DANONE", "status": "active", "legal_form": { "code": "5599", "label": "SA a conseil d'administration", "scheme": "FR-CJ" }, "activity": { "nace": "70.10", "code": "70.10Z", "label": "Activites des sieges sociaux", "scheme": "FR-NAF-REV2" }, "incorporated_on": "1955-01-01", "closed_on": null, "updated_at": "2026-10-03T04:00:00Z" } ], "meta": { "sources": [ { "name": "Official company register: France", "country": "FR", "kind": "register", "data_date": "2026-10-03" } ] } } } } }, "304": { "$ref": "#/components/responses/V2NotModified" }, "400": { "description": "query_too_short (no word of 2 characters or more in q) or invalid_parameter (neither q nor registry_id, or limit, status out of range)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2Error" } } } }, "401": { "$ref": "#/components/responses/V2Unauthorized" }, "403": { "$ref": "#/components/responses/V2Forbidden" }, "404": { "description": "country_not_supported (a country in country has no name index)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2Error" } } } }, "429": { "$ref": "#/components/responses/V2TooManyRequests" }, "500": { "$ref": "#/components/responses/V2DataUnavailable" }, "503": { "description": "server_busy, or search_unavailable when no name index is loaded yet", "headers": { "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2Error" } } } } }, "x-codeSamples": [ { "lang": "Shell", "label": "curl", "source": "curl -X GET \"https://api.jsonpage.com/v2/companies?q=danone\" \\\n -H \"X-API-Key: $JSONPAGE_API_KEY\"" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const res = await fetch(\"https://api.jsonpage.com/v2/companies?q=danone\", {\n method: \"GET\",\n headers: { \"X-API-Key\": process.env.JSONPAGE_API_KEY }\n});\nconsole.log(await res.json());" }, { "lang": "Python", "label": "Python", "source": "import os, requests\n\nres = requests.request(\"GET\", \"https://api.jsonpage.com/v2/companies?q=danone\",\n headers={\"X-API-Key\": os.environ[\"JSONPAGE_API_KEY\"]})\nprint(res.json())" }, { "lang": "PHP", "label": "PHP", "source": " \"GET\",\n CURLOPT_RETURNTRANSFER => true,\n CURLOPT_HTTPHEADER => [\"X-API-Key: \" . getenv(\"JSONPAGE_API_KEY\")],\n]);\n$data = json_decode(curl_exec($ch), true);" }, { "lang": "Ruby", "label": "Ruby", "source": "require \"net/http\"\nrequire \"json\"\n\nuri = URI(\"https://api.jsonpage.com/v2/companies?q=danone\")\nreq = Net::HTTP::Get.new(uri, \"X-API-Key\" => ENV[\"JSONPAGE_API_KEY\"])\nres = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(req) }\nputs JSON.parse(res.body)" } ] } }, "/companies/batch": { "post": { "summary": "Look up up to 100 companies in one call", "x-summary-fr": "Fiches de 100 entreprises au plus en un seul appel.", "description": "Each company counts as one request against the plan rate limit. The response keeps the requested order; each item has data, or error when the identifier is invalid or the company is not found. The body is a JSON object of at most 64 KB with ids and include only; any other field, or an unreadable body, returns 400 invalid_json.", "operationId": "batchCompaniesV2", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchRequest" }, "example": { "ids": [ "FR-552032534", "FR-000000001" ], "include": [ "vat" ] } } } }, "responses": { "200": { "description": "One item per requested identifier, in order", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BatchItem" } }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "example": { "data": [ { "id": "FR-552032534", "data": { "id": "FR-552032534", "country": "FR", "registry_id": "552032534", "name": "DANONE", "status": "active", "legal_form": { "code": "5599", "label": "SA a conseil d'administration", "scheme": "FR-CJ" }, "activity": { "nace": "70.10", "code": "70.10Z", "label": "Activites des sieges sociaux", "scheme": "FR-NAF-REV2" }, "incorporated_on": "1955-01-01", "closed_on": null, "updated_at": "2026-10-03T04:00:00Z", "vat": { "number": "FR27552032534", "status": "valid", "checked_at": "2026-09-20T10:12:00Z", "source": "EU VAT check" } } }, { "id": "FR-000000001", "data": null, "error": { "code": "not_found", "message": "No company with this identifier." } } ], "meta": { "sources": [ { "name": "Official company register: France", "country": "FR", "kind": "register", "data_date": "2026-10-03" } ] } } } } }, "400": { "$ref": "#/components/responses/V2BadRequest" }, "401": { "$ref": "#/components/responses/V2Unauthorized" }, "403": { "$ref": "#/components/responses/V2Forbidden" }, "429": { "$ref": "#/components/responses/V2TooManyRequests" }, "503": { "$ref": "#/components/responses/V2Busy" } }, "x-codeSamples": [ { "lang": "Shell", "label": "curl", "source": "curl -X POST \"https://api.jsonpage.com/v2/companies/batch\" \\\n -H \"X-API-Key: $JSONPAGE_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"ids\": [\"FR-552032534\", \"BE-0417497106\"], \"include\": [\"address\"]}'" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const res = await fetch(\"https://api.jsonpage.com/v2/companies/batch\", {\n method: \"POST\",\n headers: { \"X-API-Key\": process.env.JSONPAGE_API_KEY, \"Content-Type\": \"application/json\" },\n body: JSON.stringify({\"ids\": [\"FR-552032534\", \"BE-0417497106\"], \"include\": [\"address\"]})\n});\nconsole.log(await res.json());" }, { "lang": "Python", "label": "Python", "source": "import os, requests\n\nres = requests.request(\"POST\", \"https://api.jsonpage.com/v2/companies/batch\",\n headers={\"X-API-Key\": os.environ[\"JSONPAGE_API_KEY\"]},\n json={\"ids\": [\"FR-552032534\", \"BE-0417497106\"], \"include\": [\"address\"]})\nprint(res.json())" }, { "lang": "PHP", "label": "PHP", "source": " \"POST\",\n CURLOPT_RETURNTRANSFER => true,\n CURLOPT_HTTPHEADER => [\"X-API-Key: \" . getenv(\"JSONPAGE_API_KEY\"), \"Content-Type: application/json\"],\n CURLOPT_POSTFIELDS => json_encode([\"ids\" => [\"FR-552032534\", \"BE-0417497106\"], \"include\" => [\"address\"]]),\n]);\n$data = json_decode(curl_exec($ch), true);" }, { "lang": "Ruby", "label": "Ruby", "source": "require \"net/http\"\nrequire \"json\"\n\nuri = URI(\"https://api.jsonpage.com/v2/companies/batch\")\nreq = Net::HTTP::Post.new(uri, \"X-API-Key\" => ENV[\"JSONPAGE_API_KEY\"], \"Content-Type\" => \"application/json\")\nreq.body = {\"ids\": [\"FR-552032534\", \"BE-0417497106\"], \"include\": [\"address\"]}.to_json\nres = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(req) }\nputs JSON.parse(res.body)" } ] } }, "/monitors": { "get": { "summary": "List the monitored companies", "x-summary-fr": "Liste des entreprises surveillées.", "description": "Lists the companies monitored by the account, sorted by identifier. When a page is full, next is the identifier of its last company: pass it to after for the next page; next is null on the last page. meta.count is the number of monitored companies and meta.limit the plan limit (Discovery 2, Standard 1,000, Pro 10,000). Counts as one request.", "operationId": "listMonitorsV2", "parameters": [ { "name": "after", "in": "query", "required": false, "description": "The next value of the previous page (a company identifier).", "schema": { "type": "string" }, "example": "FR-552032534" }, { "$ref": "#/components/parameters/MonitorLimit" } ], "responses": { "200": { "description": "One page of monitored companies", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MonitorList" }, "example": { "data": [ { "company_id": "FR-552032534", "created_at": "2026-09-01T09:30:00Z", "checked_at": "2026-10-03T04:00:00Z" } ], "next": null, "meta": { "count": 1, "limit": 1000 } } } } }, "400": { "$ref": "#/components/responses/V2BadRequest" }, "401": { "$ref": "#/components/responses/V2Unauthorized" }, "403": { "$ref": "#/components/responses/V2Forbidden" }, "429": { "$ref": "#/components/responses/V2TooManyRequests" }, "500": { "$ref": "#/components/responses/V2DataUnavailable" }, "503": { "$ref": "#/components/responses/V2MonitoringUnavailable" } }, "x-codeSamples": [ { "lang": "Shell", "label": "curl", "source": "curl -X GET \"https://api.jsonpage.com/v2/monitors\" \\\n -H \"X-API-Key: $JSONPAGE_API_KEY\"" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const res = await fetch(\"https://api.jsonpage.com/v2/monitors\", {\n method: \"GET\",\n headers: { \"X-API-Key\": process.env.JSONPAGE_API_KEY }\n});\nconsole.log(await res.json());" }, { "lang": "Python", "label": "Python", "source": "import os, requests\n\nres = requests.request(\"GET\", \"https://api.jsonpage.com/v2/monitors\",\n headers={\"X-API-Key\": os.environ[\"JSONPAGE_API_KEY\"]})\nprint(res.json())" }, { "lang": "PHP", "label": "PHP", "source": " \"GET\",\n CURLOPT_RETURNTRANSFER => true,\n CURLOPT_HTTPHEADER => [\"X-API-Key: \" . getenv(\"JSONPAGE_API_KEY\")],\n]);\n$data = json_decode(curl_exec($ch), true);" }, { "lang": "Ruby", "label": "Ruby", "source": "require \"net/http\"\nrequire \"json\"\n\nuri = URI(\"https://api.jsonpage.com/v2/monitors\")\nreq = Net::HTTP::Get.new(uri, \"X-API-Key\" => ENV[\"JSONPAGE_API_KEY\"])\nres = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(req) }\nputs JSON.parse(res.body)" } ] } }, "/monitors/{id}": { "put": { "summary": "Start monitoring a company", "x-summary-fr": "Démarre la surveillance d'une entreprise.", "description": "Adds the company to the account's monitoring list. The state recorded now is the baseline: later checks compare the company with the official company registers, legal notices, beneficial ownership information and the sanctions lists, and record each difference as an event; no event is created for the past. Idempotent: 201 when the company is added, 200 when it was already monitored (also when the plan limit is reached). Counts as one request.", "operationId": "addMonitorV2", "parameters": [ { "$ref": "#/components/parameters/CompanyId" } ], "responses": { "200": { "description": "The company was already monitored", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MonitorResult" }, "example": { "data": { "company_id": "FR-552032534", "created": false } } } } }, "201": { "description": "The company is now monitored", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MonitorResult" }, "example": { "data": { "company_id": "FR-552032534", "created": true } } } } }, "400": { "$ref": "#/components/responses/V2BadRequest" }, "401": { "$ref": "#/components/responses/V2Unauthorized" }, "403": { "description": "monitor_limit_reached (the plan monitors up to 2, 1,000 or 10,000 companies) or ip_not_allowed (request from an IP address outside the account's allowlist) or product_not_enabled (the product is not enabled on the account)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2Error" } } } }, "404": { "description": "not_found (no company with this identifier)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2Error" } } } }, "429": { "$ref": "#/components/responses/V2TooManyRequests" }, "500": { "$ref": "#/components/responses/V2DataUnavailable" }, "503": { "$ref": "#/components/responses/V2MonitoringUnavailable" } }, "x-codeSamples": [ { "lang": "Shell", "label": "curl", "source": "curl -X PUT \"https://api.jsonpage.com/v2/monitors/FR-552032534\" \\\n -H \"X-API-Key: $JSONPAGE_API_KEY\"" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const res = await fetch(\"https://api.jsonpage.com/v2/monitors/FR-552032534\", {\n method: \"PUT\",\n headers: { \"X-API-Key\": process.env.JSONPAGE_API_KEY }\n});\nconsole.log(await res.json());" }, { "lang": "Python", "label": "Python", "source": "import os, requests\n\nres = requests.request(\"PUT\", \"https://api.jsonpage.com/v2/monitors/FR-552032534\",\n headers={\"X-API-Key\": os.environ[\"JSONPAGE_API_KEY\"]})\nprint(res.json())" }, { "lang": "PHP", "label": "PHP", "source": " \"PUT\",\n CURLOPT_RETURNTRANSFER => true,\n CURLOPT_HTTPHEADER => [\"X-API-Key: \" . getenv(\"JSONPAGE_API_KEY\")],\n]);\n$data = json_decode(curl_exec($ch), true);" }, { "lang": "Ruby", "label": "Ruby", "source": "require \"net/http\"\nrequire \"json\"\n\nuri = URI(\"https://api.jsonpage.com/v2/monitors/FR-552032534\")\nreq = Net::HTTP::Put.new(uri, \"X-API-Key\" => ENV[\"JSONPAGE_API_KEY\"])\nres = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(req) }\nputs JSON.parse(res.body)" } ] }, "delete": { "summary": "Stop monitoring a company", "x-summary-fr": "Arrête la surveillance d'une entreprise.", "description": "Removes the company from the monitoring list. Events already recorded stay readable. Counts as one request.", "operationId": "removeMonitorV2", "parameters": [ { "$ref": "#/components/parameters/CompanyId" } ], "responses": { "204": { "description": "The company is no longer monitored" }, "400": { "$ref": "#/components/responses/V2BadRequest" }, "401": { "$ref": "#/components/responses/V2Unauthorized" }, "403": { "$ref": "#/components/responses/V2Forbidden" }, "404": { "description": "not_monitored (the account does not monitor this company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2Error" } } } }, "429": { "$ref": "#/components/responses/V2TooManyRequests" }, "500": { "$ref": "#/components/responses/V2DataUnavailable" }, "503": { "$ref": "#/components/responses/V2MonitoringUnavailable" } }, "x-codeSamples": [ { "lang": "Shell", "label": "curl", "source": "curl -X DELETE \"https://api.jsonpage.com/v2/monitors/FR-552032534\" \\\n -H \"X-API-Key: $JSONPAGE_API_KEY\"" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const res = await fetch(\"https://api.jsonpage.com/v2/monitors/FR-552032534\", {\n method: \"DELETE\",\n headers: { \"X-API-Key\": process.env.JSONPAGE_API_KEY }\n});\nconsole.log(await res.json());" }, { "lang": "Python", "label": "Python", "source": "import os, requests\n\nres = requests.request(\"DELETE\", \"https://api.jsonpage.com/v2/monitors/FR-552032534\",\n headers={\"X-API-Key\": os.environ[\"JSONPAGE_API_KEY\"]})\nprint(res.json())" }, { "lang": "PHP", "label": "PHP", "source": " \"DELETE\",\n CURLOPT_RETURNTRANSFER => true,\n CURLOPT_HTTPHEADER => [\"X-API-Key: \" . getenv(\"JSONPAGE_API_KEY\")],\n]);\n$data = json_decode(curl_exec($ch), true);" }, { "lang": "Ruby", "label": "Ruby", "source": "require \"net/http\"\nrequire \"json\"\n\nuri = URI(\"https://api.jsonpage.com/v2/monitors/FR-552032534\")\nreq = Net::HTTP::Delete.new(uri, \"X-API-Key\" => ENV[\"JSONPAGE_API_KEY\"])\nres = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(req) }\nputs JSON.parse(res.body)" } ] } }, "/events": { "get": { "summary": "List the detected events", "x-summary-fr": "Liste des changements détectés sur les entreprises surveillées.", "description": "Lists the events of the account's monitored companies, oldest first. Event identifiers increase but are not necessarily consecutive. Pass the identifier of the last event processed to after; next is the identifier of the last event of the page, or null when there is no new event (keep your own cursor then). Events are kept 90 days. Webhook test events (test) are not listed. Counts as one request.", "operationId": "listEventsV2", "parameters": [ { "name": "after", "in": "query", "required": false, "description": "Return the events after this one. Omit to start from the oldest event kept.", "schema": { "type": "string", "pattern": "^evt_[0-9]+$" }, "example": "evt_41" }, { "$ref": "#/components/parameters/MonitorLimit" }, { "name": "company_id", "in": "query", "required": false, "description": "Return only the events of this company (global identifier). A company no longer in the register keeps its events.", "schema": { "type": "string" }, "example": "FR-552032534" } ], "responses": { "200": { "description": "One page of events, oldest first", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventList" }, "example": { "data": [ { "id": "evt_42", "type": "company.address_changed", "company_id": "FR-552032534", "detected_at": "2026-10-03T04:00:00Z", "data": { "before": "75 AV DE LA GRANDE ARMEE 75116 PARIS", "after": "7 RUE HENRI SAINTE-CLAIRE DEVILLE 92500 RUEIL-MALMAISON" } } ], "next": "evt_42" } } } }, "400": { "description": "invalid_parameter (limit out of range, or after is not an event id such as evt_42), or invalid_identifier (company_id is not a global identifier)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2Error" } } } }, "401": { "$ref": "#/components/responses/V2Unauthorized" }, "403": { "$ref": "#/components/responses/V2Forbidden" }, "429": { "$ref": "#/components/responses/V2TooManyRequests" }, "500": { "$ref": "#/components/responses/V2DataUnavailable" }, "503": { "$ref": "#/components/responses/V2MonitoringUnavailable" } }, "x-codeSamples": [ { "lang": "Shell", "label": "curl", "source": "curl -X GET \"https://api.jsonpage.com/v2/events\" \\\n -H \"X-API-Key: $JSONPAGE_API_KEY\"" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const res = await fetch(\"https://api.jsonpage.com/v2/events\", {\n method: \"GET\",\n headers: { \"X-API-Key\": process.env.JSONPAGE_API_KEY }\n});\nconsole.log(await res.json());" }, { "lang": "Python", "label": "Python", "source": "import os, requests\n\nres = requests.request(\"GET\", \"https://api.jsonpage.com/v2/events\",\n headers={\"X-API-Key\": os.environ[\"JSONPAGE_API_KEY\"]})\nprint(res.json())" }, { "lang": "PHP", "label": "PHP", "source": " \"GET\",\n CURLOPT_RETURNTRANSFER => true,\n CURLOPT_HTTPHEADER => [\"X-API-Key: \" . getenv(\"JSONPAGE_API_KEY\")],\n]);\n$data = json_decode(curl_exec($ch), true);" }, { "lang": "Ruby", "label": "Ruby", "source": "require \"net/http\"\nrequire \"json\"\n\nuri = URI(\"https://api.jsonpage.com/v2/events\")\nreq = Net::HTTP::Get.new(uri, \"X-API-Key\" => ENV[\"JSONPAGE_API_KEY\"])\nres = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(req) }\nputs JSON.parse(res.body)" } ] } }, "/autocomplete": { "get": { "summary": "Suggest companies while the user types", "x-summary-fr": "Suggestions d'entreprises pendant la saisie d'un formulaire.", "description": "For forms that complete as the user types. Answers from the name index only, without reading the full record, in a few milliseconds on the server. Words follow the name search rules of GET /v2/companies?q=: every word of 2 characters or more must appear in the name, the last word as a prefix. When q is a registry number (SIREN, SIRET, Belgian enterprise number, Swiss UID such as CHE-101.374.515, Norwegian organisation number, Finnish Business ID, Latvian registration number, Australian ABN, Singapore UEN, Japanese corporate number or UK company number), the matching company is returned directly; a 14-digit SIRET returns its company. Order: exact names first, then active companies, then companies before sole traders. Counts as one request. Call it from your backend (never expose the API key in the browser) and debounce the input (about 150 ms).", "operationId": "autocompleteV2", "parameters": [ { "name": "q", "in": "query", "required": true, "description": "Text typed by the user, a name or a registry number.", "schema": { "type": "string", "example": "carrefour" } }, { "$ref": "#/components/parameters/SearchCountry" }, { "name": "status", "in": "query", "required": false, "description": "active keeps active companies only (default); any keeps every status.", "schema": { "type": "string", "enum": [ "active", "any" ], "default": "active" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of suggestions.", "schema": { "type": "integer", "minimum": 1, "maximum": 20, "default": 8 } }, { "$ref": "#/components/parameters/IfNoneMatch" } ], "responses": { "200": { "description": "Suggestions, best match first", "headers": { "ETag": { "$ref": "#/components/headers/ETag" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Suggestion" } } } }, "example": { "data": [ { "id": "FR-652014051", "name": "CARREFOUR", "status": "active", "postal_code": "91300", "city": "MASSY", "kind": "company" } ] } } } }, "304": { "$ref": "#/components/responses/V2NotModified" }, "400": { "description": "query_too_short (no word of 2 characters or more in q) or invalid_parameter (status or limit out of range)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2Error" } } } }, "401": { "$ref": "#/components/responses/V2Unauthorized" }, "403": { "$ref": "#/components/responses/V2Forbidden" }, "404": { "description": "country_not_supported (a country in country has no name index)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2Error" } } } }, "429": { "$ref": "#/components/responses/V2TooManyRequests" }, "500": { "$ref": "#/components/responses/V2DataUnavailable" }, "503": { "$ref": "#/components/responses/V2Busy" } }, "x-codeSamples": [ { "lang": "Shell", "label": "curl", "source": "curl -X GET \"https://api.jsonpage.com/v2/autocomplete?q=danone&limit=5\" \\\n -H \"X-API-Key: $JSONPAGE_API_KEY\"" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const res = await fetch(\"https://api.jsonpage.com/v2/autocomplete?q=danone&limit=5\", {\n method: \"GET\",\n headers: { \"X-API-Key\": process.env.JSONPAGE_API_KEY }\n});\nconsole.log(await res.json());" }, { "lang": "Python", "label": "Python", "source": "import os, requests\n\nres = requests.request(\"GET\", \"https://api.jsonpage.com/v2/autocomplete?q=danone&limit=5\",\n headers={\"X-API-Key\": os.environ[\"JSONPAGE_API_KEY\"]})\nprint(res.json())" }, { "lang": "PHP", "label": "PHP", "source": " \"GET\",\n CURLOPT_RETURNTRANSFER => true,\n CURLOPT_HTTPHEADER => [\"X-API-Key: \" . getenv(\"JSONPAGE_API_KEY\")],\n]);\n$data = json_decode(curl_exec($ch), true);" }, { "lang": "Ruby", "label": "Ruby", "source": "require \"net/http\"\nrequire \"json\"\n\nuri = URI(\"https://api.jsonpage.com/v2/autocomplete?q=danone&limit=5\")\nreq = Net::HTTP::Get.new(uri, \"X-API-Key\" => ENV[\"JSONPAGE_API_KEY\"])\nres = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(req) }\nputs JSON.parse(res.body)" } ] } }, "/validate": { "get": { "summary": "Check a company identifier, a SIRET and a VAT number in one call", "x-summary-fr": "Contrôle d'un identifiant, d'un SIRET et d'un numéro de TVA en un appel.", "description": "Give id, siret, vat, or any combination of them (at least one). Spaces, dots and hyphens are ignored in siret and vat. Each check is returned with its result; a check that depends on a failed one is omitted (a malformed SIRET is not looked up). valid is true only if every check returned is ok. company is the base record with its address (and its vat block when a VAT number was checked); it is returned even when the establishment or the company is closed, and is null when the identifiers do not point to the same company or the company is not found. French, Belgian, Swiss, Norwegian (NO, the organisation number and MVA), Finnish (FI), Latvian (LV), Swedish (SE) and Estonian (EE) VAT numbers are supported: another country gives vat_country_supported=false. siret applies to France only. eori adds the check of an EORI number (see GET /eori/{number}): its shape, then whether the official service knows it; a service that does not answer leaves the check passing with the value unverifiable, as the number is not proven wrong. A French EORI must be FR followed by the SIRET of an establishment, and that SIREN must be the one of the other identifiers. Use cases: client and supplier onboarding forms, invoices (supplier SIRET and VAT), simple company identity checks. Counts as one request. Responses are sent with Cache-Control: private, max-age=60.", "operationId": "validateV2", "parameters": [ { "name": "id", "in": "query", "required": false, "description": "Global company identifier.", "schema": { "type": "string", "example": "FR-652014051" } }, { "name": "siret", "in": "query", "required": false, "description": "14-digit SIRET of a French establishment.", "schema": { "type": "string", "example": "55203253400414" } }, { "name": "vat", "in": "query", "required": false, "description": "VAT number, French (FR…), Belgian (BE followed by the 10-digit enterprise number), Swiss (the UID followed by MWST, TVA or IVA, such as CHE-105.909.036 MWST), Norwegian (NO, the organisation number and MVA, such as NO923609016MVA), Finnish (FI followed by 8 digits) Latvian (LV followed by 11 digits) Swedish (SE, the organisation number and 01) or Estonian (EE and 9 digits).", "schema": { "type": "string", "example": "FR14652014051" } }, { "name": "eori", "in": "query", "required": false, "description": "EORI number (customs identifier), a two-letter country code followed by up to 15 characters, such as FR55203253400646.", "schema": { "type": "string", "example": "FR55203253400646" } } ], "responses": { "200": { "description": "The result of every check (also when valid is false)", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Validation" } } }, "example": { "data": { "valid": true, "checks": [ { "code": "id_format", "ok": true, "value": "FR-652014051" }, { "code": "siren_key", "ok": true, "value": "652014051" }, { "code": "vat_format", "ok": true, "value": "FR14652014051" }, { "code": "identifiers_match", "ok": true, "value": "FR-652014051" }, { "code": "company_exists", "ok": true, "value": "FR-652014051" }, { "code": "company_active", "ok": true, "value": "active" }, { "code": "vat_registered", "ok": true, "value": "valid" } ], "company": { "id": "FR-652014051", "country": "FR", "registry_id": "652014051", "name": "CARREFOUR", "status": "active" } } } } } }, "400": { "description": "invalid_parameter (none of id, siret, vat and eori is given)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2Error" } } } }, "401": { "$ref": "#/components/responses/V2Unauthorized" }, "403": { "$ref": "#/components/responses/V2Forbidden" }, "429": { "$ref": "#/components/responses/V2TooManyRequests" }, "500": { "$ref": "#/components/responses/V2DataUnavailable" }, "503": { "$ref": "#/components/responses/V2Busy" } }, "x-codeSamples": [ { "lang": "Shell", "label": "curl", "source": "curl -X GET \"https://api.jsonpage.com/v2/validate?id=FR-552032534\" \\\n -H \"X-API-Key: $JSONPAGE_API_KEY\"" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const res = await fetch(\"https://api.jsonpage.com/v2/validate?id=FR-552032534\", {\n method: \"GET\",\n headers: { \"X-API-Key\": process.env.JSONPAGE_API_KEY }\n});\nconsole.log(await res.json());" }, { "lang": "Python", "label": "Python", "source": "import os, requests\n\nres = requests.request(\"GET\", \"https://api.jsonpage.com/v2/validate?id=FR-552032534\",\n headers={\"X-API-Key\": os.environ[\"JSONPAGE_API_KEY\"]})\nprint(res.json())" }, { "lang": "PHP", "label": "PHP", "source": " \"GET\",\n CURLOPT_RETURNTRANSFER => true,\n CURLOPT_HTTPHEADER => [\"X-API-Key: \" . getenv(\"JSONPAGE_API_KEY\")],\n]);\n$data = json_decode(curl_exec($ch), true);" }, { "lang": "Ruby", "label": "Ruby", "source": "require \"net/http\"\nrequire \"json\"\n\nuri = URI(\"https://api.jsonpage.com/v2/validate?id=FR-552032534\")\nreq = Net::HTTP::Get.new(uri, \"X-API-Key\" => ENV[\"JSONPAGE_API_KEY\"])\nres = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(req) }\nputs JSON.parse(res.body)" } ] } }, "/eori/{number}": { "get": { "summary": "Check an EORI number", "x-summary-fr": "Vérifier un numéro EORI (identifiant douanier).", "description": "Checks an EORI number, the customs identifier of an economic operator: a two-letter country code followed by up to 15 letters or digits (spaces, dots and hyphens are ignored; EL is read as GR). Numbers of the European Union member states and of Northern Ireland (XI) are checked with the official European verification service, GB numbers with the official British one. Switzerland (CH) and Norway (NO) get status not_applicable: the European EORI does not apply there, and this is not an error. name and address are returned only when the official service gives them, that is when the operator agreed to their publication. An official service that cannot answer gives status unverifiable and valid null: it is never reported as invalid. Answers are reused for 24 hours per number, and calls toward the official services are paced. A French EORI is FR followed by the SIRET: GET /companies/{id}?include=eori tests the one of the head office and calls it probable. Counts as one request. An unverifiable answer is sent with Cache-Control: no-store.", "operationId": "getEORI", "parameters": [ { "name": "number", "in": "path", "required": true, "description": "EORI number, such as FR55203253400646, DE1234567 or GB123456789000.", "schema": { "type": "string", "example": "FR55203253400646" } }, { "name": "company_name", "in": "query", "required": false, "description": "Name of the company to compare with the name held by customs, for a number that is not French (a French number is compared with the register). Sets name_match.", "schema": { "type": "string", "maxLength": 200 } } ], "responses": { "200": { "description": "The result of the check", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/EORICheck" } } }, "examples": { "valid": { "summary": "A registered number whose operator agreed to publish name and address", "value": { "data": { "eori": "DE1234567", "country": "DE", "status": "valid", "valid": true, "checked_at": "2026-10-11T12:00:00Z", "name": "EXEMPLE GMBH", "address": "Hauptstrasse 1, 10115, BERLIN, DE" } } }, "unverifiable": { "summary": "The official service did not answer", "value": { "data": { "eori": "DE1234567", "country": "DE", "status": "unverifiable", "valid": null, "checked_at": null, "message": "The verification service could not answer for now. This is not an invalid number, retry later." } } }, "not_applicable": { "summary": "Switzerland and Norway", "value": { "data": { "eori": "CHE105909036", "country": "CH", "status": "not_applicable", "valid": null, "checked_at": null, "message": "The European EORI verification does not apply to this country." } } } } } } }, "400": { "description": "invalid_eori (not a country code followed by up to 15 characters) or country_not_supported", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2Error" } } } }, "401": { "$ref": "#/components/responses/V2Unauthorized" }, "403": { "$ref": "#/components/responses/V2Forbidden" }, "429": { "$ref": "#/components/responses/V2TooManyRequests" }, "503": { "description": "eori_unavailable (EORI verification is not enabled on this server) or server_busy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2Error" } } } } }, "x-codeSamples": [ { "lang": "Shell", "label": "curl", "source": "curl -X GET \"https://api.jsonpage.com/v2/eori/FR55203253400646\" \\\n -H \"X-API-Key: $JSONPAGE_API_KEY\"" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const res = await fetch(\"https://api.jsonpage.com/v2/eori/FR55203253400646\", {\n method: \"GET\",\n headers: { \"X-API-Key\": process.env.JSONPAGE_API_KEY }\n});\nconsole.log(await res.json());" }, { "lang": "Python", "label": "Python", "source": "import os, requests\n\nres = requests.request(\"GET\", \"https://api.jsonpage.com/v2/eori/FR55203253400646\",\n headers={\"X-API-Key\": os.environ[\"JSONPAGE_API_KEY\"]})\nprint(res.json())" }, { "lang": "PHP", "label": "PHP", "source": " \"GET\",\n CURLOPT_RETURNTRANSFER => true,\n CURLOPT_HTTPHEADER => [\"X-API-Key: \" . getenv(\"JSONPAGE_API_KEY\")],\n]);\n$data = json_decode(curl_exec($ch), true);" }, { "lang": "Ruby", "label": "Ruby", "source": "require \"net/http\"\nrequire \"json\"\n\nuri = URI(\"https://api.jsonpage.com/v2/eori/FR55203253400646\")\nreq = Net::HTTP::Get.new(uri, \"X-API-Key\" => ENV[\"JSONPAGE_API_KEY\"])\nres = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(req) }\nputs JSON.parse(res.body)" } ] } } }, "components": { "securitySchemes": { "ApiKey": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "API key created in the dashboard; an account can hold several named keys (1, 3 or 10 depending on the plan). A rotated key keeps working for 24 hours. On the Pro plan, keys can be restricted to allowed IP addresses or ranges; other addresses get 403 ip_not_allowed. Send it in the X-API-Key header of every request. A free key is created in a minute at https://jsonpage.com/account, no card needed.", "x-description-fr": "Clé API créée dans le tableau de bord, à envoyer dans l'en-tête X-API-Key de chaque requête. Un compte peut avoir plusieurs clés nommées (1, 3 ou 10 selon le forfait). Une clé renouvelée reste valable 24 heures. Une clé gratuite se crée en une minute sur https://jsonpage.com/account, sans carte bancaire." } }, "parameters": { "CompanyId": { "name": "id", "in": "path", "required": true, "description": "Global identifier: ISO 3166-1 alpha-2 country code, a hyphen and the national registry number, for example FR-552032534, BE-0417497106, CH-101374515, NO-923609016, FI-01120389, LV-40003245752, IE-104547, SE-5560427220, EE-10137025, LT-110053842, AU-51824753556, SG-196800306E, JP-1180301018771 or GB-00445790.", "schema": { "type": "string", "pattern": "^[A-Za-z]{2}-.+$", "example": "FR-552032534" } }, "Include": { "name": "include", "in": "query", "required": false, "description": "Comma-separated optional blocks. An unknown block returns 400 unknown_include. Blocks not yet available in a country are reported in meta.includes as not_available_in_country.", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "address", "establishments", "local", "vat", "eori", "signals", "legal_events", "officers", "owners", "sanctions" ] } } }, "Fields": { "name": "fields", "in": "query", "required": false, "description": "Comma-separated base fields to keep. id and the requested blocks are always kept.", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "name", "status" ] }, "Limit": { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, "After": { "name": "after", "in": "query", "required": false, "description": "The next cursor of the previous page (in France, the SIRET of the last establishment; in Belgium and Norway, its establishment unit number). A cursor that does not belong to the company restarts from the first page.", "schema": { "type": "string" } }, "MonitorLimit": { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 100 } }, "NameQuery": { "name": "q", "in": "query", "required": false, "description": "Company name to search for. Every word of 2 characters or more must appear in the name; the last word is a prefix when it has 3 letters or more.", "schema": { "type": "string", "example": "danone" } }, "SearchCountry": { "name": "country", "in": "query", "required": false, "description": "Name search only. Comma-separated country codes; every country is searched when omitted.", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "FR", "BE", "CH", false, "LV", "FI", "AU", "SG", "JP", "GB", "IE", "SE", "EE", "LT" ] } }, "example": [ "FR", "BE" ] }, "SearchStatus": { "name": "status", "in": "query", "required": false, "description": "Name search only. active keeps active companies only.", "schema": { "type": "string", "enum": [ "active", "any" ], "default": "any" } }, "SearchLimit": { "name": "limit", "in": "query", "required": false, "description": "Name search only. Maximum number of results.", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 } }, "RegistryId": { "name": "registry_id", "in": "query", "required": false, "description": "National registry number, without country code. Required when q is not given.", "schema": { "type": "string", "example": "552032534" } }, "IfNoneMatch": { "name": "If-None-Match", "in": "header", "required": false, "description": "ETag of a previous response; the API answers 304 without a body when it is unchanged.", "schema": { "type": "string" } } }, "headers": { "ETag": { "description": "Identifies this exact response body.", "schema": { "type": "string" } }, "RateLimitRemaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } } }, "schemas": { "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } }, "V2Company": { "type": "object", "description": "Base record, identical in every country. Optional blocks appear only when requested.", "required": [ "id", "country", "registry_id", "name", "status", "legal_form", "activity", "incorporated_on", "closed_on", "updated_at" ], "properties": { "id": { "type": "string", "example": "FR-552032534" }, "country": { "type": "string", "example": "FR" }, "registry_id": { "type": "string", "example": "552032534" }, "name": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "active", "closed", "unknown" ] }, "legal_form": { "allOf": [ { "$ref": "#/components/schemas/CodeValue" } ], "type": "object", "nullable": true }, "activity": { "allOf": [ { "$ref": "#/components/schemas/Activity" } ], "type": "object", "nullable": true }, "incorporated_on": { "type": "string", "format": "date", "nullable": true }, "closed_on": { "type": "string", "format": "date", "nullable": true }, "updated_at": { "type": "string", "format": "date-time", "nullable": true }, "address": { "$ref": "#/components/schemas/Address" }, "vat": { "$ref": "#/components/schemas/VAT" }, "eori": { "$ref": "#/components/schemas/CompanyEORI" }, "signals": { "type": "array", "items": { "$ref": "#/components/schemas/Signal" } }, "legal_events": { "type": "array", "description": "Latest 20 announcements, newest first.", "items": { "$ref": "#/components/schemas/LegalEvent" } }, "owners": { "type": "array", "description": "Current persons with significant control (PSC), as published in the UK register. Ceased persons are excluded; addresses and the day of birth are never returned. Empty array when none. Available for the United Kingdom only; in the other countries it is reported in meta.includes as not_available_in_country (the French register of beneficial owners is no longer public since 31 July 2024; the other registers do not publish them).", "items": { "$ref": "#/components/schemas/Owner" } }, "sanctions": { "$ref": "#/components/schemas/Sanctions" }, "establishments": { "$ref": "#/components/schemas/EstablishmentPage" }, "local": { "type": "object", "description": "Fields specific to the country register, as published. Belgium: enterprise_number (0417.497.106), status, juridical_situation (code, label, scheme BE-JURIDICAL-SITUATION), type_of_enterprise (1 natural person, 2 legal person), juridical_form, start_date, names (language, type legal/abbreviation/commercial, value) and activities (code, nace_version, group, classification MAIN/SECO/ANCI, label). Switzerland: uid (CHE-105.909.036), ehra_id (federal register number), chid (cantonal register number), legal_form (code, label_fr, label_de, label_en), purpose (as registered), municipality (bfs_number, name), canton (two letters), names (language empty for the registered name, else de/fr/it/en/rm, and value), other_registrations (further registered offices of the same legal entity: ehra_id, chid, name, status, municipality, canton, address) and last_listed_on (closed entities only: the last day the register listed it). Norway: organisation_number (923 609 016), legal_form (code, label, scheme) and legal_form_label_no, registered_on, founded_on, in_business_enterprise_register, vat_registered and vat_registered_on, institutional_sector (code, label), employees, capital (amount, currency, type), municipality and last_listed_on. Finland: business_id (0112038-9), legal_form_label, in_trade_register, vat_registered and vat_registered_on, situation (KONK bankruptcy, SELTILA liquidation, SANE restructuring), municipality_code, other_names (type parallel/auxiliary/auxiliary_translation, value) and last_listed_on. Latvia: registration_number, register (code K commercial register, B associations and foundations…, label), termination (L liquidated, R reorganised, for a struck-off entity) and legal_form_label_lv. Ireland: company_number, company_type and status (code, label, scheme), status_since, eircode, county, last_annual_return_on, next_annual_return_due and last_accounts_on. Sweden: organisation_number (556042-7220), proceeding and deregistration (code, label, scheme), proceeding_since, business_active, marketing_restriction, other_activities, other_names (type special_business_name or foreign_language_name, value) and last_listed_on. Estonia: registry_code, status (code, label, scheme), legal_form_label_et, legal_subtype, place and last_listed_on. Lithuania: legal_entity_code, legal_form_label_lt, legal_status (code, label, scheme), legal_status_label_lt and legal_status_since. Australia: abn (51 824 753 556), acn, acn_kind, state, entity_type_label, gst (registered, status ACT/CAN, since), abn_status_since, sole_trader, other_names (type trading/business/other_trading/gift_recipient, value) and record_updated_on. Singapore: uen, entity_type (code, label, scheme SG-ENTITY-TYPE), register_status, uen_issued_on, accounts_due_on, annual_return_on, secondary_activity, former_names and sole_proprietor. Japan: corporate_number, name_kana, name_en, address_en, prefecture, prefecture_code, municipality_code, foreign_address, number_assigned_on, last_change_on, record_updated_on, closure (code, label, scheme JP-CLOSURE-CAUSE), successor_number and legal_form_label_ja.", "additionalProperties": true } } }, "CodeValue": { "type": "object", "required": [ "code", "label", "scheme" ], "properties": { "code": { "type": "string" }, "label": { "type": "string", "nullable": true }, "scheme": { "type": "string", "example": "FR-CJ" } } }, "Activity": { "type": "object", "required": [ "nace", "code", "label", "scheme" ], "properties": { "nace": { "type": "string", "nullable": true, "description": "NACE rev. 2 class, or null when the national code has no equivalent.", "example": "70.10" }, "code": { "type": "string", "example": "70.10Z" }, "label": { "type": "string", "nullable": true }, "scheme": { "type": "string", "example": "FR-NAF-REV2" } } }, "Address": { "type": "object", "required": [ "line", "postal_code", "city", "country", "formatted" ], "properties": { "line": { "type": "string", "nullable": true }, "postal_code": { "type": "string", "nullable": true }, "city": { "type": "string", "nullable": true }, "country": { "type": "string" }, "formatted": { "type": "string", "nullable": true } } }, "V2Establishment": { "type": "object", "required": [ "registry_id", "name", "head_office", "status", "activity", "opened_on", "address" ], "properties": { "registry_id": { "type": "string", "description": "For France, the 14-digit SIRET; for Belgium, the 10-digit establishment unit number (starting with 2); for Norway, the 9-digit number of the sub-unit." }, "name": { "type": "string", "nullable": true }, "head_office": { "type": "boolean" }, "status": { "type": "string", "enum": [ "active", "closed", "unknown" ] }, "activity": { "allOf": [ { "$ref": "#/components/schemas/Activity" } ], "type": "object", "nullable": true }, "opened_on": { "type": "string", "format": "date", "nullable": true }, "address": { "allOf": [ { "$ref": "#/components/schemas/Address" } ], "type": "object", "nullable": true } } }, "EstablishmentPage": { "type": "object", "required": [ "items", "next" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/V2Establishment" } }, "next": { "type": "string", "nullable": true, "description": "Cursor to pass as after; null on the last page." } } }, "VAT": { "type": "object", "required": [ "number", "status", "checked_at", "source" ], "properties": { "number": { "type": "string", "example": "FR27552032534" }, "status": { "type": "string", "enum": [ "pending", "valid", "invalid", "not_verified", "unavailable" ], "description": "pending: check scheduled in the background, retry a few seconds later. valid or invalid: result of the VAT check, reused for 30 days. not_verified: number computed but not checked by this server. Norway: valid or invalid from the VAT register flag of the register, never pending. unavailable: Switzerland only, the check could not be completed; it is retried later. For a Swiss member of a VAT group, number is the group's (for example CHE-116.281.710 MWST)." }, "checked_at": { "type": "string", "format": "date-time", "nullable": true }, "source": { "type": "string", "description": "Label of the VAT check.", "example": "EU VAT check" } } }, "CompanyEORI": { "type": "object", "description": "The EORI number a French company most likely holds: FR followed by the SIRET of its head office. The number is derived, never read from a register, so probable is always true. status is the answer of the official verification service for that number: valid (the number is registered), invalid, or unverifiable (the service did not answer, which is not an invalid number). A valid answer does not prove that the company uses this number.", "required": [ "number", "probable", "basis", "status", "valid", "checked_at" ], "properties": { "number": { "type": "string", "example": "FR55203253400646" }, "probable": { "type": "boolean", "example": true }, "basis": { "type": "string", "enum": [ "head_office_siret" ] }, "status": { "type": "string", "enum": [ "valid", "invalid", "unverifiable" ] }, "valid": { "type": "boolean", "nullable": true, "description": "true or false for a definitive answer, null when unverifiable." }, "checked_at": { "type": "string", "format": "date-time", "nullable": true } } }, "EORICheck": { "type": "object", "required": [ "eori", "country", "status", "valid", "checked_at" ], "properties": { "eori": { "type": "string", "description": "The number as checked (upper case, no spaces)." }, "country": { "type": "string", "description": "Two-letter country code of the number." }, "status": { "type": "string", "enum": [ "valid", "invalid", "unverifiable", "not_applicable" ], "description": "valid or invalid: definitive answer of the official service, reused for 24 hours. unverifiable: the service did not answer, retry later (never reported as invalid). not_applicable: Switzerland and Norway, where the European EORI does not apply." }, "valid": { "type": "boolean", "nullable": true, "description": "true or false for valid and invalid, null otherwise." }, "checked_at": { "type": "string", "format": "date-time", "nullable": true }, "name": { "type": "string", "description": "Name of the operator, only when the official service gives it (the operator agreed to its publication)." }, "address": { "type": "string", "description": "Address of the operator, only when the official service gives it." }, "name_match": { "type": "boolean", "description": "Present only for a valid number whose name is published, when the name of the company is known (the register for a French number, else the company_name parameter). true when the name held by customs designates that company (case, accents, punctuation and legal forms ignored), false when it differs, for example an EORI held by a subsidiary: check that it is the same company." }, "message": { "type": "string", "description": "Plain explanation for unverifiable and not_applicable." } } }, "Signal": { "type": "object", "required": [ "code", "since", "detail" ], "properties": { "code": { "type": "string", "enum": [ "closed", "recently_created", "insolvency_proceedings", "liquidation", "strike_off_proposed", "accounts_overdue", "confirmation_statement_overdue", "dormant" ], "description": "closed: France, Belgium, Switzerland, Norway, Finland, Latvia, Ireland, Sweden, Estonia, Lithuania, Australia, Singapore, Japan and the United Kingdom. recently_created: France, Belgium, Norway, Finland, Latvia, Ireland, Sweden, Estonia, Lithuania, Australia, Singapore and the United Kingdom. insolvency_proceedings: France, Belgium, Norway, Finland, Ireland, Sweden, Estonia, Lithuania, Singapore and the United Kingdom. liquidation (dissolution or liquidation in progress, outside bankruptcy): Belgium, Norway, Finland, Singapore, Ireland, Sweden, Estonia and Lithuania, and Switzerland and Latvia when the registered name carries the mention of liquidation (en liquidation, in liquidazione, Likvidējamā). strike_off_proposed: Singapore and the United Kingdom. accounts_overdue, dormant: United Kingdom." }, "since": { "type": "string", "format": "date", "nullable": true }, "detail": { "type": "string", "nullable": true } } }, "LegalEvent": { "type": "object", "required": [ "id", "published_on", "family", "type", "judgment", "court", "source", "url" ], "properties": { "id": { "type": "string", "example": "A202601892890" }, "published_on": { "type": "string", "format": "date" }, "family": { "type": "string", "enum": [ "insolvency", "conciliation", "professional_recovery", "deregistration", "sale", "registration", "other" ] }, "type": { "type": "string", "enum": [ "initial", "correction", "cancellation" ] }, "judgment": { "type": "object", "nullable": true, "properties": { "family": { "type": "string", "nullable": true }, "nature": { "type": "string", "nullable": true }, "date": { "type": "string", "format": "date", "nullable": true } } }, "court": { "type": "string", "nullable": true }, "source": { "type": "string", "example": "Legal notices: France" }, "url": { "type": "string", "format": "uri", "example": "…" } } }, "Owner": { "type": "object", "description": "A current person with significant control, as published in the UK register.", "required": [ "kind", "name", "control", "natures_of_control", "notified_on", "sanctioned" ], "properties": { "kind": { "type": "string", "enum": [ "individual", "corporate_entity", "legal_person", "super_secure" ], "description": "individual: natural person. corporate_entity: company on a register. legal_person: other legal person. super_secure: person whose details are protected by the register." }, "name": { "type": "string", "nullable": true, "description": "Name as published; null for super_secure.", "example": "Mr John Smith" }, "nationality": { "type": "string", "description": "Individuals only, omitted otherwise.", "example": "British" }, "country_of_residence": { "type": "string", "description": "Individuals only, omitted otherwise.", "example": "England" }, "birth": { "type": "object", "description": "Individuals only, omitted otherwise. Month and year only, as published; never the day.", "required": [ "year", "month" ], "properties": { "year": { "type": "integer", "example": 1970 }, "month": { "type": "integer", "minimum": 1, "maximum": 12, "nullable": true, "example": 5 } } }, "control": { "$ref": "#/components/schemas/OwnerControl" }, "natures_of_control": { "type": "array", "description": "Raw nature-of-control codes, as published.", "items": { "type": "string" }, "example": [ "ownership-of-shares-50-to-75-percent-as-trust", "voting-rights-more-than-25-percent", "right-to-appoint-and-remove-directors" ] }, "notified_on": { "type": "string", "format": "date", "nullable": true, "description": "Date the control was notified to the register.", "example": "2016-04-06" }, "identification": { "$ref": "#/components/schemas/OwnerIdentification" }, "sanctioned": { "type": "boolean", "description": "True when the register marks the person as sanctioned." } } }, "OwnerControl": { "type": "object", "required": [ "shares", "voting_rights", "appoints_directors", "significant_influence", "via" ], "properties": { "shares": { "allOf": [ { "$ref": "#/components/schemas/PercentRange" } ], "type": "object", "nullable": true, "description": "Band of the shares held, in percent, or null." }, "voting_rights": { "allOf": [ { "$ref": "#/components/schemas/PercentRange" } ], "type": "object", "nullable": true, "description": "Band of the voting rights held, in percent, or null." }, "appoints_directors": { "type": "boolean", "description": "Right to appoint or remove a majority of the directors." }, "significant_influence": { "type": "boolean", "description": "Significant influence or control by other means." }, "via": { "type": "array", "description": "firm and/or trust when control is held through one; empty otherwise.", "items": { "type": "string", "enum": [ "firm", "trust" ] } } } }, "PercentRange": { "type": "object", "required": [ "min", "max" ], "properties": { "min": { "type": "integer", "example": 50 }, "max": { "type": "integer", "example": 75 } } }, "OwnerIdentification": { "type": "object", "description": "Corporate owners only, omitted otherwise.", "required": [ "registration_number", "country_registered", "legal_form" ], "properties": { "registration_number": { "type": "string", "nullable": true, "example": "00686734" }, "country_registered": { "type": "string", "nullable": true, "example": "England & Wales" }, "legal_form": { "type": "string", "nullable": true, "example": "Private Limited Company" } } }, "Sanctions": { "type": "object", "description": "Screening of the company against the main international and national sanctions lists (European Union, United Nations, France, United Kingdom and United States). Only listed entities are compared, never natural persons. match means the registry number is listed as a registration number of the same country (only the EU list gives countries); possible_match means the company name equals a listed name or alias once case, accents, punctuation and legal forms are ignored. The result is indicative: no_match is not a guarantee and does not replace the customer's own due diligence (KYC/AML). Available for France, Belgium, Switzerland, Norway, Finland, Latvia, Ireland, Sweden, Estonia, Lithuania, Australia, Singapore, Japan and the United Kingdom.", "required": [ "status", "matches", "lists" ], "properties": { "status": { "type": "string", "enum": [ "no_match", "possible_match", "match" ] }, "matches": { "type": "array", "items": { "$ref": "#/components/schemas/SanctionsMatch" } }, "lists": { "type": "array", "description": "The lists screened against, with their publication date.", "items": { "$ref": "#/components/schemas/SanctionsList" } } } }, "SanctionsMatch": { "type": "object", "required": [ "list", "reference", "name", "match_type" ], "properties": { "list": { "type": "string", "enum": [ "EU", "UN", "FR", "UK", "US" ] }, "reference": { "type": "string", "description": "Reference of the listed entity in its list." }, "name": { "type": "string", "description": "Main name of the listed entity." }, "match_type": { "type": "string", "enum": [ "identifier", "name" ] }, "listed_on": { "type": "string", "format": "date", "description": "Listing date, when the list gives it." }, "programs": { "type": "array", "items": { "type": "string" }, "description": "Sanctions regimes as each list names them (EU programme code such as RUS, UN committee such as DPRK, UK regime, US program such as RUSSIA-EO14024, French legal basis).", "example": [ "RUSSIA-EO14024" ] } } }, "SanctionsList": { "type": "object", "required": [ "list", "name", "published_at", "entities" ], "properties": { "list": { "type": "string", "enum": [ "EU", "UN", "FR", "UK", "US" ] }, "name": { "type": "string", "example": "Sanctions list: European Union" }, "published_at": { "type": "string", "description": "Publication date of the list (YYYY-MM-DD), or empty when unknown." }, "entities": { "type": "integer", "description": "Number of listed entities compared." } } }, "Source": { "type": "object", "required": [ "name", "country", "kind" ], "properties": { "name": { "type": "string", "description": "Generic label of the data set; the API does not name the providers.", "example": "Official company register: France" }, "country": { "type": "string", "example": "FR" }, "kind": { "type": "string", "enum": [ "register", "legal_notices", "vat_check", "sanctions", "ownership" ] }, "data_date": { "type": "string", "description": "Date of the data (YYYY-MM-DD), when known." } } }, "Meta": { "type": "object", "required": [ "sources" ], "properties": { "sources": { "type": "array", "items": { "$ref": "#/components/schemas/Source" } }, "includes": { "type": "object", "description": "State of each requested block.", "additionalProperties": { "type": "string", "enum": [ "ok", "not_available_in_country" ] } } } }, "BatchRequest": { "type": "object", "required": [ "ids" ], "additionalProperties": false, "properties": { "ids": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "type": "string" } }, "include": { "type": "array", "items": { "type": "string", "enum": [ "address", "establishments", "local", "vat", "eori", "signals", "legal_events", "officers", "owners", "sanctions" ] } } } }, "BatchItem": { "type": "object", "required": [ "id", "data" ], "properties": { "id": { "type": "string" }, "data": { "allOf": [ { "$ref": "#/components/schemas/V2Company" } ], "type": "object", "nullable": true }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } }, "V2Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_identifier", "unknown_include", "invalid_parameter", "invalid_json", "query_too_short", "invalid_api_key", "ip_not_allowed", "product_not_enabled", "not_found", "country_not_supported", "not_available_in_country", "rate_limit_exceeded", "daily_limit_reached", "data_unavailable", "internal_error", "server_busy", "search_unavailable", "monitor_limit_reached", "not_monitored", "monitoring_unavailable" ] }, "message": { "type": "string" }, "message_en": { "type": "string", "description": "English version of the message, only for daily_limit_reached (its message is in French)." }, "upgrade_url": { "type": "string", "format": "uri", "description": "Page of the plans, only for daily_limit_reached." }, "docs": { "type": "string", "format": "uri" } } } } }, "VatRates": { "type": "object", "required": [ "country", "currency", "standard_rate", "reduced_rates", "super_reduced_rate", "super_reduced_categories", "parking_rate", "parking_categories", "zero_rated_categories", "applies_from" ], "properties": { "country": { "type": "string", "description": "ISO 3166-1 alpha-2 code (GR for Greece, GB for the United Kingdom).", "example": "FR" }, "currency": { "type": "string", "example": "EUR" }, "standard_rate": { "type": "number", "description": "Standard rate, in percent.", "example": 20 }, "reduced_rates": { "type": "array", "description": "Reduced rates, from the lowest to the highest, each with the categories it applies to.", "items": { "type": "object", "required": [ "rate", "categories" ], "properties": { "rate": { "type": "number" }, "categories": { "type": "array", "items": { "type": "string" } } } } }, "super_reduced_rate": { "type": "number", "nullable": true, "description": "Super-reduced rate, null when the country has none." }, "super_reduced_categories": { "type": "array", "items": { "type": "string" } }, "parking_rate": { "type": "number", "nullable": true, "description": "Parking (intermediate) rate, null when the country has none." }, "parking_categories": { "type": "array", "items": { "type": "string" } }, "zero_rated_categories": { "type": "array", "description": "Categories taxed at 0 percent with the right to deduct input VAT. Exemptions without that right are not listed.", "items": { "type": "string" } }, "applies_from": { "type": "string", "format": "date", "description": "Date from which these rates apply (not earlier than 2024-01-01)." }, "notes": { "type": "string", "description": "Particularities of the country, in English. Absent when there is none." } } }, "VatRatesMeta": { "type": "object", "properties": { "count": { "type": "integer", "description": "Number of countries (list only)." }, "categories": { "type": "array", "description": "The categories used in the answer, with their labels.", "items": { "type": "object", "required": [ "id", "labels" ], "properties": { "id": { "type": "string", "example": "foodstuffs" }, "labels": { "type": "object", "properties": { "fr": { "type": "string" }, "en": { "type": "string" }, "nl": { "type": "string" }, "de": { "type": "string" } } } } } } } }, "Suggestion": { "type": "object", "description": "A light search result from the name index, for autocomplete.", "required": [ "id", "name", "status", "postal_code", "city", "kind" ], "properties": { "id": { "type": "string", "example": "FR-652014051" }, "name": { "type": "string", "example": "CARREFOUR" }, "status": { "type": "string", "enum": [ "active", "closed", "unknown" ] }, "postal_code": { "type": "string", "nullable": true, "example": "91300" }, "city": { "type": "string", "nullable": true, "example": "MASSY" }, "kind": { "type": "string", "enum": [ "company", "person" ], "description": "person for a sole trader." } } }, "ValidationCheck": { "type": "object", "required": [ "code", "ok" ], "properties": { "code": { "type": "string", "enum": [ "id_format", "siren_key", "siret_format", "siret_key", "siret_exists", "siret_active", "vat_format", "vat_country_supported", "identifiers_match", "company_exists", "company_active", "vat_registered", "eori_format", "eori_siret", "eori_registered" ], "description": "id_format: the global identifier is well formed for a country served (in Switzerland, Norway and Finland, with a correct modulo-11 check digit; in Sweden, with a correct Luhn check digit; in Estonia and Lithuania, with a correct check digit). In Japan, the check digit of the corporate number is verified. In Singapore, the check letter of the UEN is verified. In Australia, the modulo-89 check of the ABN is verified. siren_key: the SIREN check digit (Luhn) is correct (France). siret_format: the SIRET has 14 digits. siret_key: the SIRET check digit (Luhn) is correct; La Poste establishments use their own rule. siret_exists: the establishment exists in the register. siret_active: the establishment is active. vat_format: the VAT number is well formed (France: the number computed from the SIREN; Belgium: BE and an enterprise number with a correct check; Switzerland: a UID with a correct check digit, followed by MWST, TVA or IVA; Norway: NO, an organisation number with a correct check digit and MVA; Finland: FI and a Business ID with a correct check digit; Latvia: LV and 11 digits; Sweden: SE, an organisation number with a correct Luhn check digit and 01; Estonia: EE and 9 digits; Lithuania: LT and 9 digits with a correct check digit). vat_country_supported: the VAT number's country is supported (France, Belgium, Switzerland, Norway, Finland, Latvia, Sweden, Estonia or Lithuania); false for another country. identifiers_match: every identifier points to the same company. company_exists: the company exists in the register. company_active: the company is active. vat_registered: verification status of the VAT number; valid, pending (the check is not complete yet, retry a few seconds later), not_verified and unavailable pass, invalid fails. eori_format: the EORI number is a two-letter code of a country covered (European Union, XI, GB, CH, NO) and up to 15 characters. eori_siret: a French EORI is FR followed by 14 digits that form a SIRET with a correct check digit. eori_registered: status of the EORI number with the official service. valid, unverifiable (the service did not answer) and not_applicable (CH, NO) pass, invalid fails. The value is the status." }, "ok": { "type": "boolean" }, "value": { "type": "string", "description": "The value checked (for company_active, vat_registered and eori_registered, the status found)." } } }, "Validation": { "type": "object", "required": [ "valid", "checks", "company" ], "properties": { "valid": { "type": "boolean", "description": "true only if every check returned is ok." }, "checks": { "type": "array", "items": { "$ref": "#/components/schemas/ValidationCheck" } }, "company": { "allOf": [ { "$ref": "#/components/schemas/V2Company" } ], "type": "object", "nullable": true, "description": "Base record with address (and vat when a French VAT number was given); null when the identifiers do not match or the company is not found." } } }, "Monitor": { "type": "object", "required": [ "company_id", "created_at", "checked_at" ], "properties": { "company_id": { "type": "string", "example": "FR-552032534" }, "created_at": { "type": "string", "format": "date-time", "description": "When monitoring started." }, "checked_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Last comparison with the registers; null until the first check." }, "watched": { "type": "object", "nullable": true, "description": "The recorded state the next comparison starts from: in_register, name, status, legal_form, activity, address, signals, signal_details, legal_events (count, null where not served), latest_legal_events, sanctions, sanctions_matches and beneficial_owners (count, null where not served).", "additionalProperties": true } } }, "MonitorResult": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "company_id", "created" ], "properties": { "company_id": { "type": "string", "description": "Canonical global identifier.", "example": "FR-552032534" }, "created": { "type": "boolean", "description": "true when the company was added by this call." } } } } }, "MonitorList": { "type": "object", "required": [ "data", "next", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Monitor" } }, "next": { "type": "string", "nullable": true, "description": "Company identifier to pass to after for the next page; null on the last page." }, "meta": { "type": "object", "required": [ "count", "limit" ], "properties": { "count": { "type": "integer", "description": "Number of companies monitored by the account." }, "limit": { "type": "integer", "description": "Number of companies the plan may monitor (Discovery 2, Standard 1,000, Pro 10,000)." } } } } }, "Event": { "type": "object", "description": "A change detected on a monitored company. The content of data depends on type: company.status_changed, company.name_changed, company.address_changed, company.activity_changed and company.legal_form_changed have before and after (after may be null); company.removed_from_register has an empty object; signal.added has code, since and detail; signal.removed has code; legal_event.published has event (a LegalEvent); sanctions.changed has before and after (sanctions statuses), added and removed (matches as LIST:reference) and matches (the current SanctionsMatch items); owner.added and owner.removed (United Kingdom) have kind and name. Monitored signals are insolvency_proceedings, liquidation, strike_off_proposed, accounts_overdue, confirmation_statement_overdue and dormant; closed and recently_created never produce signal events. test is only sent to webhooks, as a test from the dashboard, with an empty company_id.", "required": [ "id", "type", "company_id", "detected_at", "data" ], "properties": { "id": { "type": "string", "example": "evt_42" }, "type": { "type": "string", "enum": [ "company.status_changed", "company.name_changed", "company.address_changed", "company.activity_changed", "company.legal_form_changed", "company.removed_from_register", "signal.added", "signal.removed", "legal_event.published", "sanctions.changed", "owner.added", "owner.removed", "test" ] }, "company_id": { "type": "string", "example": "FR-552032534" }, "detected_at": { "type": "string", "format": "date-time" }, "data": { "anyOf": [ { "$ref": "#/components/schemas/EventFieldChange" }, { "$ref": "#/components/schemas/EventSignalAdded" }, { "$ref": "#/components/schemas/EventSignalRemoved" }, { "$ref": "#/components/schemas/EventLegalEvent" }, { "$ref": "#/components/schemas/EventSanctionsChanged" }, { "$ref": "#/components/schemas/EventOwner" }, { "type": "object", "description": "company.removed_from_register (empty) or test (message).", "additionalProperties": true } ] } }, "example": { "id": "evt_42", "type": "company.address_changed", "company_id": "FR-552032534", "detected_at": "2026-10-03T04:00:00Z", "data": { "before": "75 AV DE LA GRANDE ARMEE 75116 PARIS", "after": "7 RUE HENRI SAINTE-CLAIRE DEVILLE 92500 RUEIL-MALMAISON" } } }, "EventFieldChange": { "type": "object", "description": "company.status_changed, company.name_changed, company.address_changed, company.activity_changed, company.legal_form_changed.", "required": [ "before", "after" ], "properties": { "before": { "type": "string" }, "after": { "type": "string", "nullable": true } } }, "EventSignalAdded": { "type": "object", "required": [ "code", "since", "detail" ], "properties": { "code": { "type": "string", "enum": [ "insolvency_proceedings", "liquidation", "strike_off_proposed", "accounts_overdue", "confirmation_statement_overdue", "dormant" ] }, "since": { "type": "string", "format": "date", "nullable": true }, "detail": { "type": "string", "nullable": true } } }, "EventSignalRemoved": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string", "enum": [ "insolvency_proceedings", "liquidation", "strike_off_proposed", "accounts_overdue", "confirmation_statement_overdue", "dormant" ] } } }, "EventLegalEvent": { "type": "object", "required": [ "event" ], "properties": { "event": { "$ref": "#/components/schemas/LegalEvent" } } }, "EventSanctionsChanged": { "type": "object", "required": [ "before", "after", "added", "removed", "matches" ], "properties": { "before": { "type": "string", "enum": [ "no_match", "possible_match", "match" ] }, "after": { "type": "string", "enum": [ "no_match", "possible_match", "match" ] }, "added": { "type": "array", "items": { "type": "string" }, "example": [ "US:12345" ] }, "removed": { "type": "array", "items": { "type": "string" }, "example": [] }, "matches": { "type": "array", "items": { "$ref": "#/components/schemas/SanctionsMatch" } } } }, "EventOwner": { "type": "object", "required": [ "kind", "name" ], "properties": { "kind": { "type": "string", "enum": [ "individual", "corporate_entity", "legal_person", "super_secure" ] }, "name": { "type": "string", "nullable": true } } }, "EventList": { "type": "object", "required": [ "data", "next" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Event" } }, "next": { "type": "string", "nullable": true, "description": "Identifier of the last event of the page, to pass to after; null when there is no new event.", "example": "evt_42" } } } }, "responses": { "BadRequest": { "x-description-fr": "SIREN ou SIRET invalide", "description": "Invalid SIREN or SIRET", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "invalid_siren" } } } }, "Unauthorized": { "x-description-fr": "Clé API absente ou invalide", "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "invalid_api_key" } } } }, "Forbidden": { "x-description-fr": "Adresse IP hors liste autorisée, ou produit non activé sur le compte", "description": "ip_not_allowed (request from an IP address outside the account's allowlist, set in the dashboard on the Pro plan) or product_not_enabled (the product of the route is not enabled on the account; enable it in the dashboard)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "ip_not_allowed" } } } }, "NotFound": { "x-description-fr": "Aucun enregistrement correspondant", "description": "No matching record", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "not_found" } } } }, "TooManyRequests": { "x-description-fr": "Débit du forfait dépassé : réessayer après le délai de Retry-After", "description": "Plan request rate exceeded", "headers": { "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "rate_limit_exceeded" } } } }, "Unavailable": { "x-description-fr": "Service momentanément occupé ou indisponible", "description": "Service temporarily busy or unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "server_busy" } } } }, "DataUnavailable": { "x-description-fr": "Les données n'ont pas pu être lues", "description": "Stock data could not be read", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "data_unavailable" } } } }, "V2NotModified": { "description": "The response is unchanged since the ETag sent in If-None-Match" }, "V2BadRequest": { "x-description-fr": "Identifiant invalide, bloc include inconnu, paramètre invalide ou JSON invalide", "description": "invalid_identifier, unknown_include, invalid_parameter or invalid_json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2Error" }, "example": { "error": { "code": "invalid_identifier", "message": "The identifier is not valid for this country.", "docs": "https://jsonpage.com/docs#erreurs" } } } } }, "V2Unauthorized": { "x-description-fr": "Clé API absente ou invalide", "description": "invalid_api_key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2Error" }, "example": { "error": { "code": "invalid_api_key", "message": "The API key is missing or invalid.", "docs": "https://jsonpage.com/docs#erreurs" } } } } }, "V2Forbidden": { "x-description-fr": "Adresse IP hors liste autorisée, ou produit non activé sur le compte", "description": "ip_not_allowed (request from an IP address outside the account's allowlist, set in the dashboard on the Pro plan) or product_not_enabled (the product of the route is not enabled on the account; enable it in the dashboard)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2Error" }, "example": { "error": { "code": "ip_not_allowed", "message": "Requests from this IP address are not allowed for this key.", "docs": "https://jsonpage.com/docs#erreurs" } } } } }, "V2NotFound": { "x-description-fr": "Entreprise introuvable, pays non servi, ou information non disponible dans ce pays", "description": "not_found, country_not_supported or not_available_in_country", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2Error" }, "example": { "error": { "code": "not_found", "message": "No company with this identifier.", "docs": "https://jsonpage.com/docs#erreurs" } } } } }, "V2TooManyRequests": { "x-description-fr": "Débit du forfait dépassé (rate_limit_exceeded) ou plafond quotidien du forfait Découverte (gratuit) atteint (daily_limit_reached) : réessayer après le délai de Retry-After. Jamais facturé.", "description": "rate_limit_exceeded: the request rate of the plan is exceeded, retry after Retry-After. daily_limit_reached: the Discovery plan (free) allows 1,000 requests per day, reset at midnight UTC; Retry-After is the time left until midnight UTC, message is in French, message_en in English and upgrade_url points to the plans. Paid plans have no daily cap.", "headers": { "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2Error" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "Rate limit exceeded. Retry after the delay given in Retry-After.", "docs": "https://jsonpage.com/docs#erreurs" } } } } }, "V2DataUnavailable": { "x-description-fr": "Données momentanément indisponibles", "description": "data_unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2Error" }, "example": { "error": { "code": "data_unavailable", "message": "Data is temporarily unavailable. Please retry.", "docs": "https://jsonpage.com/docs#erreurs" } } } } }, "V2Busy": { "x-description-fr": "Serveur occupé : réessayer après le délai de Retry-After", "description": "server_busy", "headers": { "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2Error" }, "example": { "error": { "code": "server_busy", "message": "The server is busy. Retry shortly.", "docs": "https://jsonpage.com/docs#erreurs" } } } } }, "V2MonitoringUnavailable": { "x-description-fr": "Surveillance indisponible sur ce serveur", "description": "monitoring_unavailable (monitoring is not available on this server)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2Error" }, "example": { "error": { "code": "monitoring_unavailable", "message": "Monitoring is not available on this server.", "docs": "https://jsonpage.com/docs#erreurs" } } } } } } }, "x-webhooks": { "event": { "post": { "summary": "Event delivered to the account's webhook", "description": "Set up in the dashboard (Monitoring section): one HTTPS URL per account, on a public host. Private, loopback and link-local addresses are refused and redirects are not followed. Each event is POSTed with the event object as JSON body. Jsonpage-Signature is t=,v1=.\" computed with the whsec_ secret shown in the dashboard>. Verify it on the raw body in constant time and reject a t more than 5 minutes away. A 2xx answer within 15 seconds is a success; otherwise the delivery is retried after 1 min, 5 min, 30 min, 2 h, 6 h, 12 h and 24 h, then marked failed (the event stays readable through GET /v2/events). Deliveries may arrive more than once or out of order: deduplicate on the event id. A test event can be sent from the dashboard. Deliveries do not count as requests.", "operationId": "eventWebhook", "security": [], "parameters": [ { "name": "Jsonpage-Event-Id", "in": "header", "required": true, "schema": { "type": "string" }, "example": "evt_42" }, { "name": "Jsonpage-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "example": "t=1791000000,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" } } } }, "responses": { "200": { "description": "Any 2xx answer within 15 seconds acknowledges the delivery." } } } } } }