Government — entry 086 of 90
OpenMercantil
OpenMercantil is a REST API over Spain's BORME (Boletín Oficial del Registro Mercantil) company registry, aggregating roughly 2.8 million companies, 970,000 officers, and 7.1 million corporate acts from 29 official sources. Core endpoints, confirmed live, cover company and person search, per-company event timelines, and daily BORME summaries in JSON or CSV, plus premium add-ons like trust scores, ownership networks, and sanctions screening. The free tier needs no API key and has open CORS, capped at 60 requests/minute and 200/day; paid Profesional/MAX/Enterprise tiers raise those limits via an API key.
AuthenticationNone requiredCall it straight away — no key, no signup.
HTTPSSupportedTraffic is encrypted in transit.
CORSEnabledCallable directly from browser JavaScript.
PricingFreemiumA usable free tier exists, with paid plans for more volume.
FormatsJSON, CSVResponses can be requested as JSON or CSV.
GreatAPIs Score
Score97
Authentication25/25No authentication required
Pricing17/20Freemium tier available
Docs20/20Machine-readable spec file bundled
Formats15/15Supports 2 response formats
Freshness20/20Verified within 6 months
Embed this badge
<a href="https://greatapis.com/api/openmercantil/"><img src="https://greatapis.com/badge/openmercantil.svg" alt="Scored 97 on greatapis.com"></a>Auth quickstart
- No key needed — call it now.
Stored keyNo key stored
Your key is stored only in this browser (localStorage) and sent directly to the API — never to greatapis.
Endpoints
Search1
Company and person search endpoints
GET/api/v1/searchSearch published Spanish legal entities
Parameters
| Name | In | Required | Type |
|---|---|---|---|
q | query | yes | string |
limit | query | no | integer |
offset | query | no | integer |
If-None-Match | header | no | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Search results | SearchResponse |
304 | The admitted corporate search projection and exact normalized query have not changed. | — |
400 | — | — |
422 | — | — |
429 | — | — |
503 | — | — |
Companies30
Company reports and registry events
GET/api/v1/companies/compareCompare exactly two admitted companies
Parameters
| Name | In | Required | Type |
|---|---|---|---|
slugs | query | yes | array |
If-None-Match | header | no | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Two admitted companies in stable canonical order | CompanyCompareResponse |
304 | The generation-bound comparison has not changed | — |
400 | Malformed pair or both inputs resolve to the same company | CompanyCompareInvalidRequest |
404 | At least one subject is absent, personal, ambiguous, quarantined or legally withheld | CompanyCompareNotFound |
429 | — | — |
503 | The immutable company comparison projection or its authority is unavailable | — |
GET/api/v1/company/{slug}Get a company report
Parameters
| Name | In | Required | Type |
|---|---|---|---|
slug | path | yes | string |
If-None-Match | header | no | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Company report | CompanyReport |
304 | The admitted, attested company report has not changed. | — |
404 | — | — |
429 | — | — |
503 | — | — |
GET/api/v1/company/{slug}/accountsGet policy-gated filed accounts metadata
Parameters
| Name | In | Required | Type |
|---|---|---|---|
slug | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Accounts metadata list | CompanyAccountsResponse |
404 | — | — |
429 | — | — |
503 | — | — |
GET/api/v1/company/{slug}/activityActivity time series
Parameters
| Name | In | Required | Type |
|---|---|---|---|
slug | path | yes | string |
If-None-Match | header | no | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Time series | CompanyActivityResponse |
304 | The admitted activity projection has not changed. | — |
404 | — | — |
429 | — | — |
503 | Source policy, subject classification or activity projection unavailable | ErrorResponse |
GET/api/v1/company/{slug}/aeat-morosoCheck policy-gated AEAT debtor-list mention
Parameters
| Name | In | Required | Type |
|---|---|---|---|
slug | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Debtor list mention or empty | CompanyAeatDebtorResponse |
404 | — | — |
429 | — | — |
503 | — | — |
GET/api/v1/company/{slug}/bdeGet Banco de España sector ratios for a company CNAE
Parameters
| Name | In | Required | Type |
|---|---|---|---|
slug | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | CNAE sector-ratio projection or its documented empty shape | CompanyBdeResponse |
404 | — | — |
429 | — | — |
503 | — | — |
GET/api/v1/company/{slug}/cnmvGet the CNMV listed-company projection and recent events
Parameters
| Name | In | Required | Type |
|---|---|---|---|
slug | path | yes | string |
limit | query | no | integer |
If-None-Match | header | no | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | CNMV listed-company projection or its documented empty shape | CompanyCnmvResponse |
304 | The admitted company, projection generation and legal envelope have not changed | — |
400 | — | — |
404 | — | — |
422 | — | — |
429 | — | — |
503 | — | — |
GET/api/v1/company/{slug}/contractsGet PLACSP procurement notices linked to a legal entity
Parameters
| Name | In | Required | Type |
|---|---|---|---|
slug | path | yes | string |
limit | query | no | integer |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Contracts list | CompanyProcurementResponse |
400 | — | — |
404 | — | — |
422 | — | — |
429 | — | — |
500 | — | — |
503 | — | — |
GET/api/v1/company/{slug}/embargoesDocumentary embargo/garnishment mentions
Parameters
| Name | In | Required | Type |
|---|---|---|---|
slug | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Embargo mentions | CompanyEmbargoesResponse |
404 | — | — |
429 | — | — |
503 | — | — |
GET/api/v1/company/{slug}/enrichmentFail-closed public enrichment payload
Parameters
| Name | In | Required | Type |
|---|---|---|---|
slug | path | yes | string |
If-None-Match | header | no | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Enrichment payload | CompanyEnrichmentResponse |
304 | The admitted enrichment projection and source policy have not changed. | — |
404 | — | — |
429 | — | — |
503 | — | — |
GET/api/v1/company/{slug}/eventsGet paginated company events
Parameters
| Name | In | Required | Type |
|---|---|---|---|
slug | path | yes | string |
year | query | no | integer |
page | query | no | integer |
page_size | query | no | integer |
If-None-Match | header | no | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Paginated event list | CompanyEventsResponse |
304 | The generation-bound event page has not changed. | — |
400 | — | — |
404 | — | — |
422 | A validly typed year, page or page_size is outside its documented range | ErrorResponse |
429 | — | — |
500 | — | — |
503 | — | — |
GET/api/v1/company/{slug}/exportExport a single company report
Parameters
| Name | In | Required | Type |
|---|---|---|---|
slug | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Export | CompanyReport |
400 | — | — |
404 | — | — |
429 | — | — |
503 | Bounded cached company projection unavailable | OfflineProjectionError |
GET/api/v1/company/{slug}/factsGet extracted BORME facts through the legacy English alias
Parameters
| Name | In | Required | Type |
|---|---|---|---|
slug | path | yes | string |
limit | query | no | integer |
If-None-Match | header | no | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Grouped facts | CompanyFactsResponse |
304 | The attested facts report and exact limit have not changed. | — |
400 | — | — |
404 | — | — |
422 | — | — |
429 | — | — |
500 | — | — |
503 | — | — |
GET/api/v1/company/{slug}/geocodeCompany geocode projection (unavailable)
Parameters
| Name | In | Required | Type |
|---|---|---|---|
slug | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
404 | — | — |
429 | — | — |
503 | — | — |
GET/api/v1/company/{slug}/grantsGet BDNS public grants
Parameters
| Name | In | Required | Type |
|---|---|---|---|
slug | path | yes | string |
limit | query | no | integer |
If-None-Match | header | no | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Grants list | CompanyGrantsResponse |
304 | The admitted company, projection generation and legal envelope have not changed | — |
400 | — | — |
404 | — | — |
422 | — | — |
429 | — | — |
503 | — | — |
GET/api/v1/company/{slug}/ipGet policy-gated aggregated trademarks and patents
Parameters
| Name | In | Required | Type |
|---|---|---|---|
slug | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Trademarks + patents counts with states legend | — |
404 | — | — |
429 | — | — |
503 | — | — |
GET/api/v1/company/{slug}/leiGet policy-gated GLEIF LEI record
Parameters
| Name | In | Required | Type |
|---|---|---|---|
slug | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | LEI record when GLEIF is authorized | CompanyLeiResponse |
404 | — | — |
429 | — | — |
503 | — | — |
GET/api/v1/company/{slug}/networkDocumentary network projection (temporarily unavailable)
Parameters
| Name | In | Required | Type |
|---|---|---|---|
slug | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
404 | — | — |
429 | — | — |
503 | Offline projection required | OfflineProjectionError |
GET/api/v1/company/{slug}/officersGet current and historical company officers
Parameters
| Name | In | Required | Type |
|---|---|---|---|
slug | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Officer list | OfficerList |
404 | — | — |
429 | — | — |
503 | Bounded cached officer projection unavailable | OfflineProjectionError |
GET/api/v1/company/{slug}/procurementAlias of /contracts
Parameters
| Name | In | Required | Type |
|---|---|---|---|
slug | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Procurement awards (alias of contracts) | CompanyProcurementResponse |
400 | — | — |
404 | — | — |
429 | — | — |
500 | — | — |
503 | Legal-first PLACSP projection unavailable | — |
GET/api/v1/company/{slug}/relationshipsGet documentary relationships of a company
Parameters
| Name | In | Required | Type |
|---|---|---|---|
slug | path | yes | string |
type | query | no | string |
confidence | query | no | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Documented relationships list | CompanyRelationshipsResponse |
400 | — | — |
404 | — | — |
429 | — | — |
500 | — | — |
503 | — | — |
GET/api/v1/company/{slug}/risk-signalsGet documentary risk signals
Parameters
| Name | In | Required | Type |
|---|---|---|---|
slug | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Risk signals with disclaimers | — |
404 | — | — |
429 | — | — |
503 | — | — |
GET/api/v1/company/{slug}/sanctionsGet policy-gated sanctions dataset
Parameters
| Name | In | Required | Type |
|---|---|---|---|
slug | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Sanctions list when the exact dataset is authorized | CompanySanctionsResponse |
404 | — | — |
429 | — | — |
503 | — | — |
GET/api/v1/company/{slug}/scoreDocumentary completeness score (no risk/credit scoring)
Parameters
| Name | In | Required | Type |
|---|---|---|---|
slug | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Completeness score | CompanyActivityScoreResponse |
404 | — | — |
429 | — | — |
503 | — | — |
GET/api/v1/company/{slug}/similarSimilar companies (province + CNAE2 + BORME activity)
Parameters
| Name | In | Required | Type |
|---|---|---|---|
slug | path | yes | string |
limit | query | no | integer |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Similar companies list | CompanySimilarResponse |
400 | — | — |
404 | — | — |
422 | — | — |
429 | — | — |
503 | — | — |
GET/api/v1/company/{slug}/sourcesGet bounded public integration coverage for a company
Parameters
| Name | In | Required | Type |
|---|---|---|---|
slug | path | yes | string |
If-None-Match | header | no | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Generation-bound coverage for exactly four safe company integrations | CompanySourcesResponse |
304 | The admitted company, projection generation and legal envelope have not changed | — |
400 | — | — |
404 | — | — |
429 | — | — |
503 | — | — |
GET/api/v1/company/{slug}/tedGet TED notice records linked to this corporate NIF
Parameters
| Name | In | Required | Type |
|---|---|---|---|
slug | path | yes | string |
limit | query | no | integer |
If-None-Match | header | no | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Bounded TED documentary records linked to the admitted corporate NIF | CompanyTedResponse |
304 | The admitted company, projection generation and legal envelope have not changed | — |
400 | — | — |
404 | — | — |
422 | — | — |
429 | — | — |
503 | — | — |
GET/api/v1/company/{slug}/timelineGet unified multi-source company timeline
Parameters
| Name | In | Required | Type |
|---|---|---|---|
slug | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Multi-source timeline | — |
404 | — | — |
429 | — | — |
503 | — | — |
GET/api/v1/company/{slug}/wikidataGet the bounded Wikidata company metadata projection
Parameters
| Name | In | Required | Type |
|---|---|---|---|
slug | path | yes | string |
If-None-Match | header | no | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Wikidata metadata projection or its documented empty shape | CompanyWikidataResponse |
304 | The admitted company, projection generation and legal envelope have not changed | — |
400 | — | — |
404 | — | — |
429 | — | — |
503 | — | — |
GET/api/v1/empresa/{slug}/factsGet extracted BORME facts for a company
Parameters
| Name | In | Required | Type |
|---|---|---|---|
slug | path | yes | string |
limit | query | no | integer |
If-None-Match | header | no | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Grouped facts | CompanyFactsResponse |
304 | The attested facts report and exact limit have not changed. | — |
400 | — | — |
404 | — | — |
422 | — | — |
429 | — | — |
500 | — | — |
503 | — | — |
Persons4
Documentary mentions of natural persons in BORME (officer roles). Persons treated as documentary mentions only — no DNI, no contact data, no scoring.
GET/api/v1/person/searchSearch documentary mentions of persons
Parameters
| Name | In | Required | Type |
|---|---|---|---|
q | query | yes | string |
limit | query | no | integer |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Person search results | PersonSearchResponse |
400 | — | — |
422 | — | — |
429 | — | — |
503 | — | — |
GET/api/v1/person/{slug}Get documentary person mentions through the legacy English alias
Parameters
| Name | In | Required | Type |
|---|---|---|---|
slug | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Same closed person_public_v1 report as the canonical Spanish route | PersonDocumentaryReport |
404 | — | — |
429 | — | — |
503 | — | — |
GET/api/v1/persona/{slug}Get documentary mentions of a person
Parameters
| Name | In | Required | Type |
|---|---|---|---|
slug | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Person documentary mentions | PersonDocumentaryReport |
404 | — | — |
429 | — | — |
503 | — | — |
GET/api/v1/persona/{slug}/contractsPerson-to-procurement derivation (unavailable)
Parameters
| Name | In | Required | Type |
|---|---|---|---|
slug | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
429 | — | — |
503 | — | — |
Sectors4
CNAE sector aggregates, ratios and company listings
GET/api/v1/cnae/treeHierarchical CNAE tree
Responses
| Status | Description | Schema |
|---|---|---|
200 | CNAE tree | CnaeTreeResponse |
429 | — | — |
503 | — | — |
GET/api/v1/cnae/{code}CNAE code metadata
Parameters
| Name | In | Required | Type |
|---|---|---|---|
code | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | CNAE metadata | CnaeNode |
404 | — | — |
429 | — | — |
503 | — | — |
GET/api/v1/sector/{cnae}/companiesGet companies by CNAE sector code
Parameters
| Name | In | Required | Type |
|---|---|---|---|
cnae | path | yes | string |
limit | query | no | integer |
offset | query | no | integer |
sort | query | no | string |
province | query | no | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Companies in sector | SectorCompaniesResponse |
400 | — | — |
422 | — | — |
429 | — | — |
503 | Required sector-company index unavailable | ErrorResponse |
GET/api/v1/sector/{cnae}/ratiosGet sector aggregated ratios
Parameters
| Name | In | Required | Type |
|---|---|---|---|
cnae | path | yes | string |
If-None-Match | header | no | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Sector ratios | SectorRatiosResponse |
304 | Not modified; the verified projection generation and legal source authority are unchanged. | — |
404 | — | — |
429 | — | — |
503 | — | — |
BORME2
Daily BORME publications, multi-source timeline and registry events
GET/api/v1/daily/{date}Get BORME daily summary
Parameters
| Name | In | Required | Type |
|---|---|---|---|
date | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Daily summary with acts list | DailySummary |
404 | — | — |
429 | — | — |
503 | — | — |
GET/api/v1/summary/date/{date}Get a BORME daily summary through the legacy alias
Parameters
| Name | In | Required | Type |
|---|---|---|---|
date | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Daily summary with acts list | DailySummary |
404 | — | — |
429 | — | — |
Public Procurement8
Public procurement awards (PLACSP) and grants (BDNS)
GET/api/v1/contracts/top-companiesCorporate suppliers ranked by PLACSP award procedures
Parameters
| Name | In | Required | Type |
|---|---|---|---|
limit | query | no | integer |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Sanitized corporate supplier ranking | TenderSupplierResponse |
400 | — | — |
422 | — | — |
429 | — | — |
500 | — | — |
503 | PLACSP public projection unavailable | — |
GET/api/v1/contracts/top-companies.csvCorporate suppliers by award procedures (CSV)
Parameters
| Name | In | Required | Type |
|---|---|---|---|
limit | query | no | integer |
Responses
| Status | Description | Schema |
|---|---|---|
200 | CSV download | — |
400 | — | — |
422 | — | — |
429 | — | — |
500 | — | — |
503 | PLACSP public projection unavailable | — |
GET/api/v1/contracts/top-personsTop persons by PLACSP-signatory companies
Responses
| Status | Description | Schema |
|---|---|---|
429 | — | — |
503 | — | — |
GET/api/v1/contracts/top-persons.csvTop persons by PLACSP-signatory companies (CSV)
Responses
| Status | Description | Schema |
|---|---|---|
400 | — | — |
429 | — | — |
503 | — | — |
GET/api/v1/tendersSearch public procurement notices
Parameters
| Name | In | Required | Type |
|---|---|---|---|
q | query | no | string |
cpv | query | no | string |
phase | query | no | string |
province | query | no | string |
buyer_nif | query | no | string |
supplier_cif | query | no | string |
open_only | query | no | boolean |
amount_kind | query | no | string |
min_amount_eur | query | no | number |
max_amount_eur | query | no | number |
published_from | query | no | string |
published_to | query | no | string |
limit | query | no | integer |
cursor | query | no | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Sanitized notice page | TenderSearchResponse |
400 | — | — |
422 | A validly typed value is outside its documented range, a lower bound exceeds its upper bound, full-text is combined with a structured filter, CPV plus a non-date structured filter requires an offline compound projection, or supplier_cif is combined with open_only or any monetary filter before its compound offline projection exists | ErrorResponse |
429 | — | — |
500 | — | — |
503 | PLACSP dataset, public FTS, CPV prefix projection or exact CPV-date index unavailable | ErrorResponse |
GET/api/v1/tenders/statsGet non-personal procurement coverage metrics
Responses
| Status | Description | Schema |
|---|---|---|
200 | Coverage and quality metrics | TenderStats |
400 | — | — |
429 | — | — |
500 | — | — |
503 | — | — |
GET/api/v1/tenders/suppliersList corporate suppliers by award count
Parameters
| Name | In | Required | Type |
|---|---|---|---|
limit | query | no | integer |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Sanitized corporate supplier ranking | TenderSupplierResponse |
400 | — | — |
422 | limit is a valid integer but outside 1..50 | ErrorResponse |
429 | — | — |
500 | — | — |
503 | — | — |
GET/api/v1/tenders/{key}Get a sanitized procurement notice
Parameters
| Name | In | Required | Type |
|---|---|---|---|
key | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Sanitized notice detail | — |
400 | — | — |
404 | — | — |
429 | — | — |
500 | — | — |
503 | — | — |
Graph2
Corporate and person-to-company relationship graphs. Every emitted record retains the source-specific terms authorized by the active public source catalog; no blanket relicensing applies.
GET/api/v1/grafo/persona/{slug}Get person-to-company graph
Parameters
| Name | In | Required | Type |
|---|---|---|---|
slug | path | yes | string |
limit | query | no | integer |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Person graph | PersonGraphResponse |
400 | — | — |
404 | — | — |
422 | — | — |
429 | — | — |
503 | — | — |
GET/api/v1/grafo/{slug}Get corporate graph for a company
Parameters
| Name | In | Required | Type |
|---|---|---|---|
slug | path | yes | string |
max_children | query | no | integer |
If-None-Match | header | no | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Company corporate graph | CompanyGraphResponse |
304 | The admitted graph projection has not changed. | — |
400 | — | — |
404 | — | — |
422 | — | — |
429 | — | — |
503 | — | — |
Datasets8
Bulk exports (CSV / JSON / aggregated stats)
GET/api/v1/ccaa/statsGet CCAA aggregates through the suffix-less legacy alias
Parameters
| Name | In | Required | Type |
|---|---|---|---|
If-None-Match | header | no | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | CCAA stats | CcaaStatsResponse |
304 | The canonical CCAA representation and shared stats generation have not changed | — |
429 | — | — |
503 | Offline projection missing or stale | — |
GET/api/v1/ccaa/stats.jsonAggregates by autonomous community (CCAA)
Parameters
| Name | In | Required | Type |
|---|---|---|---|
If-None-Match | header | no | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | CCAA stats | CcaaStatsResponse |
304 | The CCAA representation and shared stats generation have not changed | — |
429 | — | — |
503 | — | — |
GET/api/v1/datasets/publicList generation-bound public company downloads
Parameters
| Name | In | Required | Type |
|---|---|---|---|
If-None-Match | header | no | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Atomic catalog of the three admitted public company downloads | PublicCompanyDownloadCatalog |
304 | The generation-bound download catalog has not changed | — |
429 | — | — |
503 | — | — |
GET/api/v1/export/companiesRequest an offline company export artifact (currently unavailable)
Parameters
| Name | In | Required | Type |
|---|---|---|---|
provincia | query | no | string |
tipo | query | no | string |
año | query | no | string |
limit | query | no | integer |
offset | query | no | integer |
formato | query | no | string |
Responses
| Status | Description | Schema |
|---|---|---|
400 | — | — |
401 | — | — |
403 | Scope or paid plan required | — |
429 | Export-specific rate limit exceeded | — |
503 | A pre-sanitized offline export artifact is required | OfflineProjectionError |
GET/api/v1/export/eventsBulk BORME export (offline artifact required)
Responses
| Status | Description | Schema |
|---|---|---|
503 | Pre-sanitized offline artifact is not available | OfflineProjectionError |
GET/api/v1/sectores/statsGet CNAE-sector aggregates through the suffix-less legacy alias
Parameters
| Name | In | Required | Type |
|---|---|---|---|
If-None-Match | header | no | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Sector stats | SectorStatsResponse |
304 | The canonical sector representation and shared stats generation have not changed | — |
429 | — | — |
503 | Offline projection missing or stale | — |
GET/api/v1/sectores/stats.csvAggregates by CNAE sector (CSV)
Parameters
| Name | In | Required | Type |
|---|---|---|---|
If-None-Match | header | no | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Sector stats CSV | — |
304 | The bounded sector CSV representation and shared stats generation have not changed | — |
429 | — | — |
503 | Offline projection missing or stale | — |
GET/api/v1/sectores/stats.jsonAggregates by CNAE sector
Parameters
| Name | In | Required | Type |
|---|---|---|---|
If-None-Match | header | no | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Sector stats | SectorStatsResponse |
304 | The sector representation and shared stats generation have not changed | — |
429 | — | — |
503 | — | — |
Sources2
Source catalog metadata, freshness and integration status
GET/api/v1/sources/freshnessPer-source freshness map
Parameters
| Name | In | Required | Type |
|---|---|---|---|
If-None-Match | header | no | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Freshness map | — |
304 | The authorized freshness representation and shared stats generation have not changed | — |
429 | — | — |
503 | The required offline freshness projection is absent, or the public-source legal policy cannot produce an authorized projection. This endpoint fails closed and never falls back to live connector telemetry. | OfflineProjectionError |
GET/api/v1/sources/statusMinimized public source metadata
Parameters
| Name | In | Required | Type |
|---|---|---|---|
If-None-Match | header | no | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Fail-closed public source projection | PublicSourceStatusResponse |
304 | The minimized source-status representation and shared stats generation have not changed | — |
429 | — | — |
503 | — | — |
Integrations2
Public read-only connector catalog. Never exposes credentials, OAuth tokens, webhook secrets or operator actions.
GET/api/v1/integrationsList public integration capabilities
Parameters
| Name | In | Required | Type |
|---|---|---|---|
capability | query | no | string |
If-None-Match | header | no | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Public integration catalog | IntegrationListResponse |
304 | The legal catalog and technical transport snapshot have not changed | — |
400 | — | — |
429 | — | — |
503 | — | — |
GET/api/v1/integrations/{slug}Get one public integration contract
Parameters
| Name | In | Required | Type |
|---|---|---|---|
slug | path | yes | string |
If-None-Match | header | no | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Public integration metadata | IntegrationDetailResponse |
304 | The legal decision and technical transport snapshot have not changed | — |
400 | — | — |
404 | — | — |
429 | — | — |
503 | — | — |
System2
Service health and metadata
GET/api/v1/healthService health
Parameters
| Name | In | Required | Type |
|---|---|---|---|
If-None-Match | header | no | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Health response | HealthResponse |
304 | The exact offline health representation and shared stats generation have not changed | — |
429 | — | — |
503 | — | — |
GET/api/v1/statsPublished public-dataset counters
Parameters
| Name | In | Required | Type |
|---|---|---|---|
If-None-Match | header | no | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Stats response | — |
304 | The company-public generation and bounded statistics representation have not changed. | — |
429 | — | — |
503 | — | — |
User57
Authenticated Panel Pro endpoints — segments, lists, notes, tags, exports, audit. Requires session cookie (browser) and X-CSRF-Token header for mutations.
GET/api/v1/csrfGet a live same-origin CSRF token
Responses
| Status | Description | Schema |
|---|---|---|
200 | Session CSRF state | — |
POST/api/v1/persons/lookupRun an authenticated KYC documentary lookup
Parameters
| Name | In | Required | Type |
|---|---|---|---|
X-CSRF-Token | header | yes | string |
Request body
application/json — KycPersonLookupRequest (required)
Responses
| Status | Description | Schema |
|---|---|---|
200 | Documentary lookup result with disclaimer and usage | KycPersonLookupResponse |
400 | — | — |
401 | — | — |
402 | Plan or monthly KYC quota does not permit the lookup | — |
403 | Invalid CSRF token | — |
429 | — | — |
503 | KYC helper unavailable | — |
GET/api/v1/persons/lookup/historyGet the caller's redacted KYC lookup history
Parameters
| Name | In | Required | Type |
|---|---|---|---|
limit | query | no | integer |
offset | query | no | integer |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Redacted KYC lookup history | KycPersonLookupHistoryResponse |
400 | — | — |
401 | — | — |
402 | Plan does not include KYC lookup | — |
422 | — | — |
503 | KYC helper unavailable | — |
GET/api/v1/persons/lookup/usageGet the caller's KYC lookup allowance and usage
Responses
| Status | Description | Schema |
|---|---|---|
200 | KYC tier and usage metadata | KycPersonLookupUsageResponse |
401 | — | — |
503 | KYC helper unavailable | — |
POST/api/v1/resend-verificationResend the account email-verification link
Parameters
| Name | In | Required | Type |
|---|---|---|---|
X-CSRF-Token | header | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Verification email accepted by transport | VerificationDispatchResponse |
401 | — | — |
403 | Invalid CSRF token | — |
429 | — | — |
502 | Mail transport unavailable | — |
GET/api/v1/user/api-credentialsList API credential metadata
Parameters
| Name | In | Required | Type |
|---|---|---|---|
limit | query | no | integer |
cursor | query | no | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Credential metadata and allowed scope catalog | — |
400 | — | — |
401 | — | — |
422 | — | — |
503 | Account, credential schema or cursor-signing service unavailable | — |
POST/api/v1/user/api-credentialsCreate an API credential
Parameters
| Name | In | Required | Type |
|---|---|---|---|
X-CSRF-Token | header | yes | string |
Idempotency-Key | header | yes | string |
Request body
application/json — ApiCredentialCreateRequest (required)
Responses
| Status | Description | Schema |
|---|---|---|
201 | Credential created, or its encrypted one-time response replayed for the same key and payload | ApiCredentialOneTimeResponse |
400 | — | — |
401 | — | — |
403 | Invalid CSRF token | — |
409 | Active credential limit, Idempotency-Key payload conflict, or expired replay window | — |
429 | — | — |
503 | Credential pepper, idempotency encryption keyring/schema, or account service unavailable | — |
DELETE/api/v1/user/api-credentials/{id}Revoke one API credential
Parameters
| Name | In | Required | Type |
|---|---|---|---|
id | path | yes | integer |
X-CSRF-Token | header | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Credential revoked | CredentialRevokedResponse |
401 | — | — |
403 | Invalid CSRF token | — |
404 | — | — |
429 | — | — |
503 | Account security or credential schema unavailable | — |
POST/api/v1/user/api-credentials/{id}/rotateRotate one API credential
Parameters
| Name | In | Required | Type |
|---|---|---|---|
id | path | yes | integer |
X-CSRF-Token | header | yes | string |
Idempotency-Key | header | yes | string |
Request body
application/json — ApiCredentialRotateRequest
Responses
| Status | Description | Schema |
|---|---|---|
200 | Rotated, or the exact replacement token replayed for the same key and payload | ApiCredentialOneTimeResponse |
400 | — | — |
401 | — | — |
403 | Invalid CSRF token | — |
404 | — | — |
409 | Idempotency-Key payload conflict or expired replay window | — |
429 | — | — |
503 | Credential pepper, idempotency encryption keyring/schema, or account service unavailable | — |
GET/api/v1/user/auditAudit log (MAX/Enterprise only)
Parameters
| Name | In | Required | Type |
|---|---|---|---|
limit | query | no | integer |
offset | query | no | integer |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Audit entries | UserAuditResponse |
400 | — | — |
401 | — | — |
402 | Upgrade required | — |
422 | — | — |
GET/api/v1/user/exportsExport history + monthly usage
Parameters
| Name | In | Required | Type |
|---|---|---|---|
limit | query | no | integer |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Recent + usage_summary {used, max, remaining, pct, unlimited} | UserExportListResponse |
400 | — | — |
401 | — | — |
422 | — | — |
GET/api/v1/user/exports/usageMonthly export quota usage only
Responses
| Status | Description | Schema |
|---|---|---|
200 | Usage summary | ExportUsageResponse |
GET/api/v1/user/listsList user lists
Responses
| Status | Description | Schema |
|---|---|---|
200 | Lists with tier_max | UserListListResponse |
POST/api/v1/user/listsCreate list
Parameters
| Name | In | Required | Type |
|---|---|---|---|
X-CSRF-Token | header | yes | string |
Request body
application/json — UserListCreateRequest (required)
Responses
| Status | Description | Schema |
|---|---|---|
201 | Created | UserListCreatedResponse |
400 | — | — |
401 | — | — |
403 | Invalid CSRF | — |
GET/api/v1/user/lists/{id}Get list + items
Parameters
| Name | In | Required | Type |
|---|---|---|---|
id | path | yes | integer |
Responses
| Status | Description | Schema |
|---|---|---|
200 | List + items | UserListDetail |
PUT/api/v1/user/lists/{id}Replace mutable list fields
Parameters
| Name | In | Required | Type |
|---|---|---|---|
id | path | yes | integer |
X-CSRF-Token | header | yes | string |
Request body
application/json — UserListUpdateRequest (required)
Responses
| Status | Description | Schema |
|---|---|---|
200 | Updated | OkResponse |
400 | — | — |
401 | — | — |
403 | Invalid CSRF | — |
404 | — | — |
PATCH/api/v1/user/lists/{id}Patch mutable list fields
Parameters
| Name | In | Required | Type |
|---|---|---|---|
id | path | yes | integer |
X-CSRF-Token | header | yes | string |
Request body
application/json — UserListUpdateRequest (required)
Responses
| Status | Description | Schema |
|---|---|---|
200 | Updated | OkResponse |
400 | — | — |
401 | — | — |
403 | Invalid CSRF | — |
404 | — | — |
DELETE/api/v1/user/lists/{id}Delete list and its items
Parameters
| Name | In | Required | Type |
|---|---|---|---|
id | path | yes | integer |
X-CSRF-Token | header | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Deleted | OkResponse |
401 | — | — |
403 | Invalid CSRF | — |
POST/api/v1/user/lists/{id}/itemsAdd item to list
Parameters
| Name | In | Required | Type |
|---|---|---|---|
id | path | yes | integer |
X-CSRF-Token | header | yes | string |
Request body
application/json — UserListItemCreateRequest (required)
Responses
| Status | Description | Schema |
|---|---|---|
201 | Added | OkResponse |
400 | — | — |
401 | — | — |
403 | Invalid CSRF | — |
404 | — | — |
DELETE/api/v1/user/lists/{id}/items/{item_id}Remove item from list
Parameters
| Name | In | Required | Type |
|---|---|---|---|
id | path | yes | integer |
item_id | path | yes | integer |
X-CSRF-Token | header | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Removed | OkResponse |
401 | — | — |
403 | Invalid CSRF | — |
404 | — | — |
GET/api/v1/user/meCurrent authenticated user
Responses
| Status | Description | Schema |
|---|---|---|
200 | User profile | UserMeResponse |
401 | — | — |
GET/api/v1/user/notesRecent notes
Parameters
| Name | In | Required | Type |
|---|---|---|---|
limit | query | no | integer |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Notes | UserNoteListResponse |
400 | — | — |
401 | — | — |
422 | — | — |
POST/api/v1/user/notesCreate private note
Parameters
| Name | In | Required | Type |
|---|---|---|---|
X-CSRF-Token | header | yes | string |
Request body
application/json — UserNoteCreateRequest (required)
Responses
| Status | Description | Schema |
|---|---|---|
201 | Created | UserNoteCreatedResponse |
400 | — | — |
401 | — | — |
403 | Invalid CSRF | — |
GET/api/v1/user/notes/for/{type}/{id}Notes for a target
Parameters
| Name | In | Required | Type |
|---|---|---|---|
type | path | yes | string |
id | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Notes list | UserNotesForTargetResponse |
GET/api/v1/user/notes/{id}Get note
Parameters
| Name | In | Required | Type |
|---|---|---|---|
id | path | yes | integer |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Note | UserNote |
PUT/api/v1/user/notes/{id}Replace mutable note fields
Parameters
| Name | In | Required | Type |
|---|---|---|---|
id | path | yes | integer |
X-CSRF-Token | header | yes | string |
Request body
application/json — UserNoteUpdateRequest (required)
Responses
| Status | Description | Schema |
|---|---|---|
200 | Updated | OkResponse |
400 | — | — |
401 | — | — |
403 | Invalid CSRF | — |
404 | — | — |
PATCH/api/v1/user/notes/{id}Patch mutable note fields
Parameters
| Name | In | Required | Type |
|---|---|---|---|
id | path | yes | integer |
X-CSRF-Token | header | yes | string |
Request body
application/json — UserNoteUpdateRequest (required)
Responses
| Status | Description | Schema |
|---|---|---|
200 | Updated | OkResponse |
400 | — | — |
401 | — | — |
403 | Invalid CSRF | — |
404 | — | — |
DELETE/api/v1/user/notes/{id}Delete note
Parameters
| Name | In | Required | Type |
|---|---|---|---|
id | path | yes | integer |
X-CSRF-Token | header | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Deleted | OkResponse |
401 | — | — |
403 | Invalid CSRF | — |
GET/api/v1/user/orgGet the current organization, seats and visible members
Responses
| Status | Description | Schema |
|---|---|---|
200 | Organization context | UserOrganizationResponse |
401 | — | — |
503 | Organization service unavailable | — |
POST/api/v1/user/orgCreate an organization
Parameters
| Name | In | Required | Type |
|---|---|---|---|
X-CSRF-Token | header | yes | string |
Request body
application/json — UserOrganizationNameRequest (required)
Responses
| Status | Description | Schema |
|---|---|---|
201 | Organization created | OrganizationCreatedResponse |
400 | — | — |
401 | — | — |
402 | Plan does not include teams | — |
403 | Invalid CSRF | — |
409 | User already belongs to an organization | — |
503 | Organization service unavailable | — |
PUT/api/v1/user/orgRename the current organization
Parameters
| Name | In | Required | Type |
|---|---|---|---|
X-CSRF-Token | header | yes | string |
Request body
application/json — UserOrganizationNameRequest (required)
Responses
| Status | Description | Schema |
|---|---|---|
200 | Organization renamed | OkResponse |
400 | — | — |
401 | — | — |
403 | Owner permission or CSRF required | — |
404 | — | — |
503 | Organization service unavailable | — |
POST/api/v1/user/org/invitesCreate or renew an organization invitation
Parameters
| Name | In | Required | Type |
|---|---|---|---|
X-CSRF-Token | header | yes | string |
Request body
application/json — UserOrganizationInviteRequest (required)
Responses
| Status | Description | Schema |
|---|---|---|
201 | Invitation created or renewed without token | OrganizationInviteCreatedResponse |
400 | — | — |
401 | — | — |
403 | Owner/admin permission or CSRF required | — |
409 | No organization, duplicate member or no free seat | — |
429 | — | — |
503 | Organization or email service unavailable | — |
DELETE/api/v1/user/org/invites/{id}Cancel a pending organization invitation
Parameters
| Name | In | Required | Type |
|---|---|---|---|
id | path | yes | integer |
X-CSRF-Token | header | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Invitation cancelled | OkResponse |
401 | — | — |
403 | Owner/admin permission or CSRF required | — |
404 | — | — |
503 | Organization service unavailable | — |
POST/api/v1/user/org/invites/{id}/resendRotate and resend an organization invitation
Parameters
| Name | In | Required | Type |
|---|---|---|---|
id | path | yes | integer |
X-CSRF-Token | header | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Invitation resent | EmailDispatchResponse |
401 | — | — |
403 | Owner/admin permission or CSRF required | — |
404 | — | — |
409 | No free seat for an expired invitation | — |
429 | — | — |
503 | Organization or email service unavailable | — |
POST/api/v1/user/org/leaveLeave the current organization
Parameters
| Name | In | Required | Type |
|---|---|---|---|
X-CSRF-Token | header | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Organization left | OkResponse |
401 | — | — |
403 | Invalid CSRF | — |
404 | — | — |
409 | Owner cannot leave before transferring ownership | — |
503 | Organization service unavailable | — |
PUT/api/v1/user/org/members/{id}Change an organization member role
Parameters
| Name | In | Required | Type |
|---|---|---|---|
id | path | yes | integer |
X-CSRF-Token | header | yes | string |
Request body
application/json — UserOrganizationMemberRoleRequest (required)
Responses
| Status | Description | Schema |
|---|---|---|
200 | Role updated | OkResponse |
400 | — | — |
401 | — | — |
403 | Owner permission or CSRF required | — |
404 | — | — |
503 | Organization service unavailable | — |
DELETE/api/v1/user/org/members/{id}Remove a member from the organization
Parameters
| Name | In | Required | Type |
|---|---|---|---|
id | path | yes | integer |
X-CSRF-Token | header | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Member removed | OkResponse |
400 | — | — |
401 | — | — |
403 | Owner/admin permission or CSRF required | — |
404 | — | — |
503 | Organization service unavailable | — |
GET/api/v1/user/personaCurrent persona config + available list
Responses
| Status | Description | Schema |
|---|---|---|
200 | Persona config | UserPersonaResponse |
401 | — | — |
POST/api/v1/user/personaSet persona_primary
Parameters
| Name | In | Required | Type |
|---|---|---|---|
X-CSRF-Token | header | yes | string |
Request body
application/json — UserPersonaUpdateRequest (required)
Responses
| Status | Description | Schema |
|---|---|---|
200 | Updated | UserPersonaSelectedResponse |
400 | Invalid persona slug | — |
401 | — | — |
403 | Invalid CSRF | — |
GET/api/v1/user/segmentsList user segments
Parameters
| Name | In | Required | Type |
|---|---|---|---|
pinned | query | no | string |
limit | query | no | integer |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Segments list with tier_max | UserSegmentListResponse |
400 | — | — |
401 | — | — |
422 | — | — |
POST/api/v1/user/segmentsCreate segment
Parameters
| Name | In | Required | Type |
|---|---|---|---|
X-CSRF-Token | header | yes | string |
Request body
application/json — UserSegmentCreateRequest (required)
Responses
| Status | Description | Schema |
|---|---|---|
201 | Created | UserSegmentCreatedResponse |
400 | Malformed/unknown filter, legally unavailable legacy filter, missing effective anchor or tier limit | ErrorResponse |
401 | — | — |
422 | Individually valid filters do not have a safe indexed combination | ErrorResponse |
GET/api/v1/user/segments/{id}Get segment
Parameters
| Name | In | Required | Type |
|---|---|---|---|
id | path | yes | integer |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Segment | UserSegment |
404 | — | — |
PUT/api/v1/user/segments/{id}Replace mutable segment fields
Parameters
| Name | In | Required | Type |
|---|---|---|---|
id | path | yes | integer |
X-CSRF-Token | header | yes | string |
Request body
application/json — UserSegmentUpdateRequest (required)
Responses
| Status | Description | Schema |
|---|---|---|
200 | Updated | OkResponse |
400 | Malformed/unknown or legally unavailable filter | ErrorResponse |
401 | — | — |
403 | Invalid CSRF | — |
404 | — | — |
422 | Individually valid filters do not have a safe indexed combination | ErrorResponse |
PATCH/api/v1/user/segments/{id}Patch mutable segment fields
Parameters
| Name | In | Required | Type |
|---|---|---|---|
id | path | yes | integer |
X-CSRF-Token | header | yes | string |
Request body
application/json — UserSegmentUpdateRequest (required)
Responses
| Status | Description | Schema |
|---|---|---|
200 | Updated | OkResponse |
400 | Malformed/unknown or legally unavailable filter | ErrorResponse |
401 | — | — |
403 | Invalid CSRF | — |
404 | — | — |
422 | Individually valid filters do not have a safe indexed combination | ErrorResponse |
DELETE/api/v1/user/segments/{id}Delete segment
Parameters
| Name | In | Required | Type |
|---|---|---|---|
id | path | yes | integer |
X-CSRF-Token | header | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Deleted | OkResponse |
401 | — | — |
403 | Invalid CSRF | — |
POST/api/v1/user/segments/{id}/pinToggle pin
Parameters
| Name | In | Required | Type |
|---|---|---|---|
id | path | yes | integer |
X-CSRF-Token | header | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | New pinned state | UserSegmentPinResponse |
401 | — | — |
403 | Invalid CSRF | — |
404 | — | — |
POST/api/v1/user/segments/{id}/runExecute segment filters → companies
Parameters
| Name | In | Required | Type |
|---|---|---|---|
id | path | yes | integer |
limit | query | no | integer |
X-CSRF-Token | header | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Bounded result rows; count equals rows.length and is not a global total | UserSegmentRunResponse |
400 | Malformed/unknown or legally unavailable saved filter | ErrorResponse |
401 | — | — |
403 | Invalid CSRF | — |
404 | — | — |
422 | Saved filters are valid individually but lack a safe indexed combination | ErrorResponse |
503 | Canonical authority, legal layer, immutable company sidecar or bounded query unavailable | ErrorResponse |
GET/api/v1/user/tagsList user tags with counts
Responses
| Status | Description | Schema |
|---|---|---|
200 | Tags + stats | UserTagListResponse |
POST/api/v1/user/tagsCreate tag
Parameters
| Name | In | Required | Type |
|---|---|---|---|
X-CSRF-Token | header | yes | string |
Request body
application/json — UserTagCreateRequest (required)
Responses
| Status | Description | Schema |
|---|---|---|
201 | Created | UserTagCreatedResponse |
400 | — | — |
401 | — | — |
403 | Invalid CSRF | — |
DELETE/api/v1/user/tags/{id}Delete tag and assignments
Parameters
| Name | In | Required | Type |
|---|---|---|---|
id | path | yes | integer |
X-CSRF-Token | header | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Deleted | OkResponse |
401 | — | — |
403 | Invalid CSRF | — |
POST/api/v1/user/tags/{id}/assignAssign tag to target
Parameters
| Name | In | Required | Type |
|---|---|---|---|
id | path | yes | integer |
X-CSRF-Token | header | yes | string |
Request body
application/json — UserTagAssignmentRequest (required)
Responses
| Status | Description | Schema |
|---|---|---|
200 | Assigned | OkResponse |
400 | — | — |
401 | — | — |
403 | Invalid CSRF | — |
404 | — | — |
POST/api/v1/user/tags/{id}/unassignUnassign tag from target
Parameters
| Name | In | Required | Type |
|---|---|---|---|
id | path | yes | integer |
X-CSRF-Token | header | yes | string |
Request body
application/json — UserTagAssignmentRequest (required)
Responses
| Status | Description | Schema |
|---|---|---|
200 | Unassigned | OkResponse |
400 | — | — |
401 | — | — |
403 | Invalid CSRF | — |
404 | — | — |
GET/api/v1/user/webhooksList outbound webhook metadata
Responses
| Status | Description | Schema |
|---|---|---|
200 | Webhook metadata | — |
401 | — | — |
503 | Account or webhook security schema unavailable | — |
POST/api/v1/user/webhooksCreate an outbound webhook
Parameters
| Name | In | Required | Type |
|---|---|---|---|
X-CSRF-Token | header | yes | string |
Idempotency-Key | header | yes | string |
Request body
application/json — OutboundWebhookCreateRequest (required)
Responses
| Status | Description | Schema |
|---|---|---|
201 | Created, or the exact signing secret replayed for the same key and payload | OutboundWebhookOneTimeResponse |
400 | — | — |
401 | — | — |
403 | Invalid CSRF token | — |
409 | Idempotency-Key payload conflict or expired replay window | — |
429 | — | — |
503 | Webhook service, secret keyring, or durable idempotency schema/keyring unavailable | — |
PATCH/api/v1/user/webhooks/{id}Update an outbound webhook
Parameters
| Name | In | Required | Type |
|---|---|---|---|
id | path | yes | integer |
X-CSRF-Token | header | yes | string |
Request body
application/json — OutboundWebhookUpdateRequest (required)
Responses
| Status | Description | Schema |
|---|---|---|
200 | Updated metadata | WebhookUpdatedResponse |
400 | — | — |
401 | — | — |
403 | Invalid CSRF token | — |
404 | — | — |
429 | — | — |
503 | Account security or webhook schema unavailable | — |
DELETE/api/v1/user/webhooks/{id}Delete an outbound webhook
Parameters
| Name | In | Required | Type |
|---|---|---|---|
id | path | yes | integer |
X-CSRF-Token | header | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Deleted | DeletedResponse |
401 | — | — |
403 | Invalid CSRF token | — |
404 | — | — |
429 | — | — |
503 | Account security or webhook schema unavailable | — |
POST/api/v1/user/webhooks/{id}/rotateRotate an outbound webhook signing secret
Parameters
| Name | In | Required | Type |
|---|---|---|---|
id | path | yes | integer |
X-CSRF-Token | header | yes | string |
Idempotency-Key | header | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Rotated, or the exact replacement signing secret replayed for the same key | OutboundWebhookOneTimeResponse |
400 | — | — |
401 | — | — |
403 | Invalid CSRF token | — |
404 | — | — |
409 | Idempotency-Key payload conflict or expired replay window | — |
429 | — | — |
503 | Account security, encryption keyring or webhook schema unavailable | — |
Billing8
Session-bound Stripe checkout, invoices and portal contracts. External actions are bounded, idempotent and never exposed through the public MCP.
GET/api/v1/billing/invoicesList the authenticated user's invoices and subscription
Responses
| Status | Description | Schema |
|---|---|---|
200 | Local billing projection | BillingInvoicesResponse |
401 | — | — |
429 | — | — |
GET/api/v1/billing/portalRedirect to the authenticated user's Stripe portal
Responses
| Status | Description | Schema |
|---|---|---|
302 | Redirect to Stripe Customer Portal | — |
400 | — | — |
401 | — | — |
429 | — | — |
503 | Action budget or Stripe unavailable | — |
POST/api/v1/billing/portalCreate a Stripe portal session as JSON
Parameters
| Name | In | Required | Type |
|---|---|---|---|
X-CSRF-Token | header | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Stripe Customer Portal URL | StripeSessionResponse |
400 | — | — |
401 | — | — |
403 | Invalid CSRF token | — |
429 | — | — |
503 | Action budget or Stripe unavailable | — |
POST/api/v1/checkoutCreate a subscription Checkout session
Parameters
| Name | In | Required | Type |
|---|---|---|---|
X-CSRF-Token | header | yes | string |
Idempotency-Key | header | no | string |
Request body
application/json (required)
Responses
| Status | Description | Schema |
|---|---|---|
200 | Checkout URL and Stripe session id | StripeSessionResponse |
400 | — | — |
401 | — | — |
403 | Invalid CSRF token | — |
413 | Request body too large | — |
429 | — | — |
503 | Action budget or Stripe unavailable | — |
POST/api/v1/credits/checkoutCreate an idempotent credit-pack Checkout session
Parameters
| Name | In | Required | Type |
|---|---|---|---|
X-CSRF-Token | header | yes | string |
Idempotency-Key | header | no | string |
Request body
application/json (required)
Responses
| Status | Description | Schema |
|---|---|---|
200 | Checkout URL and Stripe session id | StripeSessionResponse |
400 | — | — |
401 | — | — |
403 | Invalid CSRF token | — |
413 | Request body too large | — |
429 | — | — |
503 | Action budget or Stripe unavailable | — |
POST/api/v1/donationCreate a one-time donation Checkout session
Parameters
| Name | In | Required | Type |
|---|---|---|---|
Idempotency-Key | header | no | string |
Request body
application/json (required)
Responses
| Status | Description | Schema |
|---|---|---|
200 | Checkout URL and Stripe session id | StripeSessionResponse |
400 | — | — |
413 | Request body too large | — |
429 | — | — |
503 | Action budget or Stripe unavailable | — |
POST/api/v1/portalCreate a Stripe Customer Portal session through the legacy alias
Parameters
| Name | In | Required | Type |
|---|---|---|---|
X-CSRF-Token | header | no | string |
Request body
application/x-www-form-urlencoded
Responses
| Status | Description | Schema |
|---|---|---|
200 | Stripe Customer Portal URL | StripeSessionResponse |
400 | — | — |
401 | — | — |
403 | Invalid or missing CSRF token | ErrorResponse |
429 | — | — |
503 | Action-budget storage or Stripe Customer Portal is unavailable | ErrorResponse |
POST/api/v1/stripe-webhookReceive a signed Stripe event
Parameters
| Name | In | Required | Type |
|---|---|---|---|
Stripe-Signature | header | yes | string |
Request body
application/json — StripeWebhookEventRequest (required)
Responses
| Status | Description | Schema |
|---|---|---|
200 | Event accepted, deliberately ignored, or already terminal. All response bodies are non-secret acknowledgements. | — |
400 | Signature missing/invalid, or the raw request stream cannot be read | — |
413 | Raw callback body exceeds 512 KiB | RequestBodyTooLargeError |
500 | Inbox persistence or event processing failed; Stripe must retry | — |
503 | Another worker owns an active lease or a signed OpenMercantil checkout cannot yet be resolved to its authoritative account owner; Stripe must retry | — |
Support2
Customer-support writes. Anonymous creation requires explicit privacy consent; replies require an authenticated owner session and CSRF. Ticket data is never exposed through the public MCP.
POST/api/v1/support/ticketCreate a customer-support ticket
Request body
application/json — SupportTicketCreateRequest (required)
Responses
| Status | Description | Schema |
|---|---|---|
201 | Ticket created; only its internal numeric id and non-secret public reference are returned | SupportTicketCreatedResponse |
400 | Invalid JSON fields, validation failure or missing strict privacy consent | SupportRequestErrorResponse |
413 | Request body exceeds 32 KiB | RequestBodyTooLargeError |
429 | API plan quota exhausted or the per-IP ceiling of 5 ticket creations per hour was reached | SupportRequestErrorResponse |
503 | The account database or migrated support schema is unavailable; creation fails closed | SupportErrorResponse |
POST/api/v1/support/ticket/{id}/replyReply to a support ticket owned by the authenticated user
Parameters
| Name | In | Required | Type |
|---|---|---|---|
id | path | yes | integer |
X-CSRF-Token | header | yes | string |
Request body
application/json — SupportReplyRequest (required)
Responses
| Status | Description | Schema |
|---|---|---|
200 | Reply persisted | OkResponse |
400 | Reply validation failed or the ticket is closed | SupportRequestErrorResponse |
401 | — | — |
403 | Invalid CSRF token, ticket not found under this account, or caller is not the owner | SupportErrorResponse |
413 | Request body exceeds 32 KiB | RequestBodyTooLargeError |
429 | — | — |
503 | The action-budget store, account database or migrated support schema is unavailable; reply fails closed | SupportRequestErrorResponse |
Legal7
Spanish mercantile-law layer (derecho mercantil): legislation corpus + article texts + act→norm bridge. Distributes the consolidated BOE legal corpus structured by OpenMercantil so LLMs and agents can cite it as a source. License: consolidated text from the BOE, reused under Ley 37/2007 (re-use of public sector information); the official version is always boe.es. Informational only — NOT legal advice. Court judgments are NOT exposed here (CENDOJ is kept as a citation-index only, per CGPJ Reglamento 3/2010); this layer distributes legislation + the act↔norm index.
POST/api/v1/empresa/{slug}/informe-legalCreate the authenticated user's redacted corporate legal report
Parameters
| Name | In | Required | Type |
|---|---|---|---|
slug | path | yes | string |
X-CSRF-Token | header | yes | string |
Request body
application/json — LegalReportRequest
Responses
| Status | Description | Schema |
|---|---|---|
200 | Redacted documentary corporate report and server-owned charging result | LegalReportResponse |
400 | — | — |
401 | — | — |
402 | Insufficient credits or the idempotent charge could not be completed | LegalReportPaymentRequiredError |
403 | Invalid or missing CSRF token | ErrorResponse |
404 | Corporate subject not found or the slug is classified as a natural-person subject | ErrorResponse |
413 | Request body exceeds 32 KiB | RequestBodyTooLargeError |
429 | — | — |
503 | Action-budget storage, legal source policy, report helper, account schema or credit ledger unavailable; generation fails closed | ErrorResponse |
GET/api/v1/legal/act-mapBORME act type → governing norm bridge (full or single)
Responses
| Status | Description | Schema |
|---|---|---|
200 | Full act→norm map with license envelope | LegalActMapResponse |
429 | — | — |
503 | — | — |
GET/api/v1/legal/act-map/{acto}Governing norm for a single BORME act type
Parameters
| Name | In | Required | Type |
|---|---|---|---|
acto | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Single act→norm mapping | LegalActMapEntry |
404 | — | — |
429 | — | — |
503 | — | — |
GET/api/v1/legal/article/{norm}/{n}Consolidated text of a single article
Parameters
| Name | In | Required | Type |
|---|---|---|---|
norm | path | yes | string |
n | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Consolidated article text | LegalArticleResponse |
404 | — | — |
429 | — | — |
503 | — | — |
GET/api/v1/legal/normIndex mercantile-law norms through the singular legacy alias
Responses
| Status | Description | Schema |
|---|---|---|
200 | Norm index with license, attribution and disclaimer envelope | LegalNormsIndexResponse |
429 | — | — |
503 | — | — |
GET/api/v1/legal/norm/{slug}Detail of a single mercantile-law norm (with act↔norm bridge)
Parameters
| Name | In | Required | Type |
|---|---|---|---|
slug | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Norm detail with key articles, regulated acts and a citable fact | LegalNormResponse |
404 | — | — |
429 | — | — |
503 | — | — |
GET/api/v1/legal/normsIndex of core Spanish mercantile-law norms
Responses
| Status | Description | Schema |
|---|---|---|
200 | Norm index with license/attribution/disclaimer envelope | LegalNormsIndexResponse |
429 | — | — |
503 | — | — |
Try it
Developer reference
Base URL
https://openmercantil.esRate limit
60 requests/minute and 200 requests/day per IP on the free tier; higher tiers up to 600/minute and 50,000/day
Key endpoints
- GET/api/v1/search
- GET/api/v1/company/{slug}
- GET/api/v1/health
Availability
Uptime100%
Median latency596 ms
Last checkUp · 400 · Sep 2026
Changelog
Spec version1.9.3
Tracked paths118
- gained an OpenAPI spec and a status page