OpenMercantil Persons API

openapi: 3.1.0
info:
  title: OpenMercantil Persons API
  version: 1.9.3
  summary: Versioned public-read, browser-account, billing, support and provider-callback contracts.
  description: 'Public JSON API for Spanish company information derived from BORME and other public sources.
    OpenMercantil is an independent informational service; it is NOT the BOE, BORME or Registro Mercantil
    and does NOT replace official certificates or registry extracts.


    **Rate limits.** Free: 60 req/min y 200 req/día por IP. Planes superiores (Profesional 5.000 req/día,
    MAX 50.000 req/día, Enterprise 500.000+ req/día) según cuenta y API key. Cabeceras `X-RateLimit-Limit`,
    `X-RateLimit-Remaining`, `X-RateLimit-Reset`, `X-OpenMercantil-Plan`, `Retry-After`.


    **License and attribution.** Source-specific metadata in each response and the active versioned source
    catalog prevails. OpenMercantil does not relicense upstream content under a blanket license. Unknown,
    review and restricted datasets are omitted or return `503 legal_layer_unavailable`. BOE/BORME material
    is re-used under Ley 37/2007 and its official version remains boe.es. Court judgments are not exposed;
    CENDOJ remains citation-index only under CGPJ Reglamento 3/2010.


    **Machine-readable catalog (DCAT-AP-ES):** https://openmercantil.es/catalog.rdf'
  termsOfService: https://openmercantil.es/terminos-de-uso
  contact:
    name: OpenMercantil
    url: https://openmercantil.es/soporte
    email: social@openmercantil.es
  license:
    name: Source-specific upstream terms; see response catalog metadata
    url: https://openmercantil.es/terminos-de-uso
  x-publisher:
    name: OpenMercantil
    url: https://openmercantil.es/
    email: social@openmercantil.es
  x-spatial: http://publications.europa.eu/resource/authority/country/ESP
  x-temporal: 2009-01-01/..
  x-language: es
  x-dcat-catalog: https://openmercantil.es/catalog.rdf
  x-rate-limit:
    free:
      per_min: 60
      per_day: 200
      kind: anonymous-ip
    profesional:
      per_min: 120
      per_day: 5000
      kind: api-key
    max:
      per_min: 600
      per_day: 50000
      kind: api-key
    enterprise:
      per_min: 1200
      per_day: 500000
      kind: contract
  x-methodology: https://openmercantil.es/metodologia
  x-sources: https://openmercantil.es/fuentes
  x-corrections: https://openmercantil.es/correcciones
  x-contract-status: Public read, browser-account and provider-callback surfaces are explicitly separated
    in this contract. Operator/admin routes are excluded. The public MCP consumes only the allowlisted
    GET read plane.
  x-account-segment-contract:
    projection: company_public_v2 immutable corporate sidecar
    synchronous_row_cap: 500
    bounded_count_cap: 50001
    count_semantics: The segment run response count is the number of rows returned, never a global total.
      Dataset preview uses total_is_lower_bound=true and total_lower_bound when the bounded count reaches
      50001.
    related_web_dataset_surface:
      preview_path: /mi-cuenta/datasets/preview
      export_path: /mi-cuenta/datasets/export.csv
      synchronous_export_max_rows: 500
      overflow_status: 503
      overflow_error: async_export_required
  x-company-identity-contract:
    version: '1.0'
    projection: company_public_v2 immutable generation-bound corporate sidecar
    applies_to: Every /api/v1/company/{slug}*, /api/v1/empresa/{slug}* and /api/v1/grafo/{slug} read before
      any report, cache, graph or dataset lookup. /api/v1/companies/compare resolves both requested subjects
      in one bounded company_public_v2 batch before either row is exposed; MCP company tools inherit these
      preflights through REST.
    resolution:
      published: canonical corporate slug admitted
      safe_alias: internally canonicalized and Content-Location emitted
      withheld: neutral 404; includes absent, personal and ambiguous/quarantined identities
      unavailable: 503 with no-store; clients must not infer absence
    search: Exact corporate CIF, exact canonical/safe-alias slug, or bounded name_prefix2 pool scored
      in application code. DNI/NIE and ambiguous CIFs return zero items.
    public_company_count: company_public_projection_state.row_count
servers:
- url: https://openmercantil.es
  description: Production
tags:
- name: Persons
  description: Documentary mentions of natural persons in BORME (officer roles). Persons treated as documentary
    mentions only — no DNI, no contact data, no scoring.
paths:
  /api/v1/company/{slug}/officers:
    get:
      security:
      - {}
      - apiKey: []
      - bearerAuth: []
      x-api-credential-scope: companies:read
      operationId: getCompanyBySlugOfficers
      tags:
      - Companies
      - Persons
      summary: Get current and historical company officers
      description: Return at most 500 officer mentions from the same cached, policy-filtered company projection
        used by the canonical company route. The JSON body is capped at 1 MiB. Persons are documentary
        mentions only — no DNI, contact data or personal address.
      x-rate-limit: plan policy (see info.x-rate-limit)
      parameters:
      - name: slug
        in: path
        required: true
        schema:
          type: string
          example: banco-santander-s-a
      responses:
        '200':
          headers:
            X-Data-Sources:
              $ref: '#/components/headers/XDataSources'
            X-Source-Catalog-Version:
              $ref: '#/components/headers/XSourceCatalogVersion'
            X-Attribution-Required:
              $ref: '#/components/headers/XAttributionRequired'
          description: Officer list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OfficerList'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          description: Bounded cached officer projection unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OfflineProjectionError'
  /api/v1/persona/{slug}:
    get:
      security:
      - {}
      - apiKey: []
      - bearerAuth: []
      x-api-credential-scope: people:read
      operationId: getPersonaBySlug
      tags:
      - Persons
      summary: Get documentary mentions of a person
      description: Return an exact, attested person_public_v1 documentary-mention report bound to the
        same company_public_v2 source generation. Available is 200/private no-store; absent, withheld,
        ambiguous or quarantined is a neutral 404; authority, hash, binding or generation failure is 503/no-store.
        No raw persons fallback. No DNI/NIE, contact/address, photo/social data, enrichment, sanctions,
        scoring, person-procurement inference, identity resolution or vigency inference.
      parameters:
      - name: slug
        in: path
        required: true
        schema:
          type: string
          example: calero-brazalez-juan-jose
      responses:
        '200':
          headers:
            X-Data-Sources:
              $ref: '#/components/headers/XDataSources'
            X-Source-Catalog-Version:
              $ref: '#/components/headers/XSourceCatalogVersion'
            X-Attribution-Required:
              $ref: '#/components/headers/XAttributionRequired'
            Cache-Control:
              schema:
                type: string
              description: no-store
          description: Person documentary mentions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PersonDocumentaryReport'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/PublicReadUnavailable'
  /api/v1/person/{slug}:
    get:
      operationId: getLegacyPersonBySlug
      tags:
      - Persons
      summary: Get documentary person mentions through the legacy English alias
      description: Deprecated alias of `GET /api/v1/persona/{slug}`. The response remains a neutral set
        of attributed BORME documentary mentions, never an identity profile.
      deprecated: true
      x-replaced-by: /api/v1/persona/{slug}
      parameters:
      - name: slug
        in: path
        required: true
        schema:
          type: string
          example: calero-brazalez-juan-jose
      responses:
        '200':
          description: Same closed person_public_v1 report as the canonical Spanish route
          headers:
            Content-Location:
              schema:
                type: string
              description: Canonical /api/v1/persona/{slug} path
            X-Data-Sources:
              $ref: '#/components/headers/XDataSources'
            X-Source-Catalog-Version:
              $ref: '#/components/headers/XSourceCatalogVersion'
            X-Attribution-Required:
              $ref: '#/components/headers/XAttributionRequired'
            Cache-Control:
              schema:
                type: string
                const: private, no-store
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PersonDocumentaryReport'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/PublicReadUnavailable'
  /api/v1/person/search:
    get:
      security:
      - {}
      - apiKey: []
      - bearerAuth: []
      x-api-credential-scope: people:read
      operationId: getPersonSearch
      x-query-contract:
        allowed:
        - q
        - limit
        unknown: 400 invalid_parameter
        non_scalar: 400 invalid_parameter
        lexical: 400 invalid_parameter
        range: 422 validation_failed
      tags:
      - Persons
      - Search
      summary: Search documentary mentions of persons
      description: Search only person_public_search_v1, bounded to 50 results and revalidated against
        the activated company_public_v2 generation. Results are unresolved name mentions, never identity
        profiles. Authority failure is 503/no-store, not an empty result. No raw persons, enrichment or
        person-procurement fallback.
      x-rate-limit: free 60/min · 200/day
      parameters:
      - name: q
        in: query
        required: true
        schema:
          type: string
          minLength: 2
          maxLength: 200
          example: garcia
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 50
          default: 20
      responses:
        '200':
          headers:
            X-Data-Sources:
              $ref: '#/components/headers/XDataSources'
            X-Source-Catalog-Version:
              $ref: '#/components/headers/XSourceCatalogVersion'
            X-Attribution-Required:
              $ref: '#/components/headers/XAttributionRequired'
            Cache-Control:
              schema:
                type: string
                const: private, no-store
          description: Person search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PersonSearchResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '422':
          $ref: '#/components/responses/ValidationFailed'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/PublicReadUnavailable'
  /api/v1/persona/{slug}/contracts:
    get:
      operationId: getPersonaBySlugContracts
      tags:
      - Persons
      - Public Procurement
      summary: Person-to-procurement derivation (unavailable)
      description: Fail-closed derived route. It always returns 503 before reading data because `person_contracts_v1`
        is not authorized. A future implementation requires a new reviewed projection and contract version.
      deprecated: true
      x-rate-limit: plan policy (see info.x-rate-limit)
      parameters:
      - name: slug
        in: path
        required: true
        schema:
          type: string
      responses:
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/LegalLayerUnavailable'
components:
  headers:
    NoStoreCacheControl:
      description: Error responses must not be stored.
      schema:
        type: string
        const: no-store
    XAttributionRequired:
      description: Optional. When present, comma-separated public source aliases whose attribution terms
        must accompany reuse.
      schema:
        type: string
        minLength: 1
        pattern: ^[a-z0-9][a-z0-9_.-]*(,[a-z0-9][a-z0-9_.-]*)*$
      example: placsp
    XDataSources:
      description: Comma-separated aliases from the active public source catalog that contributed to the
        response. Omitted only when a valid exact filter returns an empty representation with zero contributing
        sources.
      schema:
        type: string
        minLength: 1
        pattern: ^[a-z0-9][a-z0-9_.-]*(,[a-z0-9][a-z0-9_.-]*)*$
      example: borme,placsp
    XSourceCatalogVersion:
      description: Mandatory on every successful public GET. Exact version of the legal source catalog
        used to authorize the response.
      schema:
        type: string
        minLength: 1
      example: 2026-07-12.2
  responses:
    BadRequest:
      description: Invalid request
      headers:
        Cache-Control:
          $ref: '#/components/headers/NoStoreCacheControl'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    LegalLayerUnavailable:
      description: 'Controlled fail-closed denial: the required dataset or legal layer is absent, invalid,
        unsupported or not authorized for this public surface.'
      headers:
        Cache-Control:
          $ref: '#/components/headers/NoStoreCacheControl'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error: legal_layer_unavailable
            detail: Este dataset no esta habilitado para redistribucion publica por la politica de fuentes
              activa.
            source_catalog_version: 2026-07-12.2
    NotFound:
      description: Resource not found
      headers:
        Cache-Control:
          $ref: '#/components/headers/NoStoreCacheControl'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    PublicReadUnavailable:
      description: The public read failed closed because its legal source catalog, subject classification,
        bounded projection, database helper or required artifact is unavailable. Clients must not infer
        an empty result.
      headers:
        Cache-Control:
          description: Unavailable public reads are never cacheable.
          schema:
            type: string
            const: no-store
        Retry-After:
          description: Optional number of seconds to wait before retrying.
          schema:
            type: integer
            minimum: 1
      content:
        application/json:
          schema:
            anyOf:
            - $ref: '#/components/schemas/ProjectionUnavailableError'
            - $ref: '#/components/schemas/ErrorResponse'
          examples:
            legal_layer:
              value:
                error: legal_layer_unavailable
            company_identity:
              value:
                error: company_public_projection_unavailable
            projection:
              value:
                error: projection_unavailable
                detail: La proyección pública requerida no está disponible.
                projection: wikidata_company_v1
    TooManyRequests:
      description: Rate limit exceeded
      headers:
        Retry-After:
          description: Seconds to wait before retrying.
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    ValidationFailed:
      description: The query is lexically valid but outside a documented numeric or length bound, or uses
        an unsupported indexed combination.
      headers:
        Cache-Control:
          $ref: '#/components/headers/NoStoreCacheControl'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    ErrorResponse:
      type: object
      description: Closed compatibility envelope for public/account errors. Route-specific schemas narrow
        these fields further where required.
      required:
      - error
      properties:
        error:
          type: string
          minLength: 1
        message:
          type: string
        detail:
          type: string
        code:
          type: string
        status:
          type:
          - integer
          - string
        projection:
          type: string
        reason:
          type: string
        source_catalog_version:
          type: string
        allowed_parameters:
          type: array
          uniqueItems: true
          items:
            type: string
        slug:
          type: string
        key:
          type: string
        maximum:
          type: integer
          minimum: 1
        parameter:
          type: string
        fields:
          type: array
          items:
            type: string
        max_bytes:
          type: integer
          minimum: 1
        allowed:
          type: array
          items:
            $ref: '#/components/schemas/JsonValue'
        valid:
          type: array
          items:
            $ref: '#/components/schemas/JsonValue'
        date:
          type: string
        login_url:
          type: string
        plan:
          type: string
        limited_by:
          type: string
          enum:
          - minute
          - day
        daily_limit:
          type: integer
          minimum: 1
        reset_at:
          type: integer
          minimum: 1
        reset_at_human:
          type: string
          format: date-time
        retry_after_s:
          type: integer
          minimum: 1
        retry_after:
          type: integer
          minimum: 1
        upgrade:
          type: string
          format: uri
        upgrade_url:
          type: string
        action:
          type: string
        limit:
          type: integer
          minimum: 0
        remaining:
          type: integer
          minimum: 0
        needed:
          type: integer
          minimum: 0
        shortfall:
          type: integer
          minimum: 0
        ok:
          type: boolean
        _alias_of:
          type: string
      additionalProperties: false
    JsonValue:
      description: A JSON value used only inside explicitly documented extension maps.
      oneOf:
      - type:
        - string
        - number
        - boolean
        - 'null'
      - type: array
        items:
          $ref: '#/components/schemas/JsonValue'
      - type: object
        additionalProperties:
          $ref: '#/components/schemas/JsonValue'
    OfficerDocumentaryMention:
      type: object
      description: Documentary officer mention. It never contains DNI, contact details or a personal address.
      properties:
        name:
          type: string
        person_slug:
          type:
          - string
          - 'null'
        role:
          type:
          - string
          - 'null'
        appointed_at:
          type:
          - string
          - 'null'
        ended_at:
          type:
          - string
          - 'null'
        source:
          type:
          - string
          - 'null'
        source_url:
          type:
          - string
          - 'null'
          format: uri
      additionalProperties:
        $ref: '#/components/schemas/JsonValue'
    OfficerList:
      type: array
      maxItems: 500
      items:
        $ref: '#/components/schemas/OfficerDocumentaryMention'
    OfflineProjectionError:
      type: object
      required:
      - error
      properties:
        error:
          type: string
        projection:
          type:
          - string
          - 'null'
        derivation:
          type:
          - string
          - 'null'
        detail:
          type:
          - string
          - 'null'
      additionalProperties: false
    PersonDocumentaryPosition:
      type: object
      required:
      - company
      - company_name
      - company_slug
      - cif
      - role
      - since
      - until
      - documentary_status
      - vigency_verified
      - source_slug
      - source_url
      properties:
        company:
          type: string
          minLength: 1
        company_name:
          type: string
          minLength: 1
        company_slug:
          type: string
          pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$
        cif:
          type: string
          description: Admitted legal-entity CIF; never a natural-person identifier.
        role:
          type:
          - string
          - 'null'
        since:
          type:
          - string
          - 'null'
          format: date
        until:
          type:
          - string
          - 'null'
          format: date
        documentary_status:
          type: string
          enum:
          - open_documentary_mention
          - historical_documentary_mention
        vigency_verified:
          type: boolean
          const: false
        source_slug:
          type: string
          const: borme
        source_url:
          type: string
          format: uri
          const: https://www.boe.es/diario_borme/
      additionalProperties: false
    PersonDocumentaryReport:
      type: object
      description: Exact person_public_v1 report. It groups unresolved BORME name mentions and never proves
        identity or current vigency.
      required:
      - slug
      - name
      - first_seen
      - last_seen
      - companies_count
      - active_positions
      - inactive_positions
      - subject_type
      - identity_resolution
      - positions_semantics
      - _legal_notice
      - _correction_channel
      - schema_version
      - status
      - projection
      - _source_catalog
      - _data_sources_used
      properties:
        slug:
          type: string
          pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$
        name:
          type: string
          minLength: 1
        first_seen:
          type:
          - string
          - 'null'
          format: date
        last_seen:
          type:
          - string
          - 'null'
          format: date
        companies_count:
          type: integer
          minimum: 1
        active_positions:
          type: array
          items:
            $ref: '#/components/schemas/PersonDocumentaryPosition'
        inactive_positions:
          type: array
          items:
            $ref: '#/components/schemas/PersonDocumentaryPosition'
        subject_type:
          type: string
          const: person_documentary_mentions
        identity_resolution:
          type: string
          const: not_performed
        positions_semantics:
          type: string
          minLength: 1
        _legal_notice:
          type: string
          minLength: 1
        _correction_channel:
          type: string
          format: uri
          const: https://openmercantil.es/proteccion-de-datos/derechos
        schema_version:
          type: string
          const: person_documentary_report_v1
        status:
          type: string
          const: available
        projection:
          $ref: '#/components/schemas/PersonPublicProjectionMetadata'
        _source_catalog:
          $ref: '#/components/schemas/SourceCatalogEnvelope'
        _data_sources_used:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/PublicSourcePolicyMetadata'
        _attributions:
          type: object
          additionalProperties:
            type: string
      additionalProperties: false
    PersonPublicProjectionMetadata:
      type: object
      required:
      - name
      - schema_version
      - contract_sha256
      - source_generation
      - content_sha256
      - projected_at
      properties:
        name:
          type: string
          const: person_public_v1
        schema_version:
          type: string
          const: '1.0'
        contract_sha256:
          type: string
          pattern: ^[a-f0-9]{64}$
        source_generation:
          type: string
          pattern: ^cpv2-[a-f0-9]{64}$
        content_sha256:
          type: string
          pattern: ^[a-f0-9]{64}$
        projected_at:
          type: string
          format: date-time
      additionalProperties: false
    PersonSearchItem:
      type: object
      description: Documentary person search result; no DNI, contact data or personal address.
      required:
      - slug
      - name
      - mentions_count
      - companies_count
      - first_seen
      - last_seen
      - subject_type
      - identity_resolution
      - source_slug
      properties:
        slug:
          type: string
          pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$
        name:
          type: string
          minLength: 1
        mentions_count:
          type: integer
          minimum: 1
        companies_count:
          type: integer
          minimum: 1
        first_seen:
          type:
          - string
          - 'null'
          format: date
        last_seen:
          type:
          - string
          - 'null'
          format: date
        subject_type:
          type: string
          const: person_documentary_mentions
        identity_resolution:
          type: string
          const: not_performed
        source_slug:
          type: string
          const: borme
      additionalProperties: false
    PersonSearchResponse:
      type: object
      required:
      - schema_version
      - status
      - query
      - count
      - items
      - subject_type
      - identity_resolution
      - projection
      - _legal_notice
      - _source_catalog
      - _data_sources_used
      properties:
        schema_version:
          type: string
          const: person_search_v1
        status:
          type: string
          const: available
        query:
          type: string
          minLength: 2
          maxLength: 200
        count:
          type: integer
          minimum: 0
          maximum: 50
        items:
          type: array
          maxItems: 50
          items:
            $ref: '#/components/schemas/PersonSearchItem'
        subject_type:
          type: string
          const: person_documentary_mentions
        identity_resolution:
          type: string
          const: not_performed
        projection:
          $ref: '#/components/schemas/PersonPublicProjectionMetadata'
        _legal_notice:
          type: string
          minLength: 1
        _source_catalog:
          $ref: '#/components/schemas/SourceCatalogEnvelope'
        _data_sources_used:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/PublicSourcePolicyMetadata'
        _attributions:
          type: object
          additionalProperties:
            type: string
      additionalProperties: false
    ProjectionUnavailableError:
      type: object
      description: Fail-closed projection outage. Clients must not reinterpret this response as an empty
        or negative result.
      required:
      - error
      - detail
      - projection
      properties:
        error:
          type: string
          const: projection_unavailable
        detail:
          type: string
        projection:
          type: string
      additionalProperties: false
    PublicSourcePolicyMetadata:
      type: object
      additionalProperties: false
      required:
      - slug
      - name
      - license
      - attribution_required
      - reuse_conditions
      - policy_effective_date
      - reviewed_at
      - catalog_version
      properties:
        slug:
          type: string
        name:
          type: string
        license:
          type: string
        license_url:
          type:
          - string
          - 'null'
          format: uri
        attribution_required:
          type: boolean
        attribution_text:
          type:
          - string
          - 'null'
        official_url:
          type:
          - string
          - 'null'
          format: uri
        reuse_conditions:
          type: string
          description: Condiciones de reutilizacion que el consumidor debe conservar al presentar o transformar
            el dato.
        policy_effective_date:
          type: string
          format: date
        reviewed_at:
          type: string
          format: date
        data_updated_at:
          type:
          - string
          - 'null'
          format: date-time
        catalog_version:
          type: string
    SourceCatalogEnvelope:
      type: object
      required:
      - catalog_version
      - policy_fingerprint
      - sources
      properties:
        catalog_version:
          type: string
        policy_fingerprint:
          type: string
        policy_effective_date:
          type: string
          format: date
        sources:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/PublicSourcePolicyMetadata'
      additionalProperties: false
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: X-API-Key
      description: Optional opaque omk_* API credential for public GETs. Anonymous access remains valid;
        a credential with the operation's x-api-credential-scope (or public:read) selects its account
        quota. Never place credentials in query strings.
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: opaque omk_* credential
      description: 'Optional Authorization: Bearer transport for the same opaque omk_* API credential
        accepted by X-API-Key. It is not a JWT or OAuth access token.'