Dato Capital Companies API

openapi: 3.2.0
info:
  title: DatoCapital Companies API
  version: '3.0'
  summary: Commercial company-data REST API.
  description: 'Read-only access to companies, directors, and filings across the

    major European business registries plus a long tail of offshore

    jurisdictions.


    Authenticate with a bearer token (`Authorization: Bearer dc_…`).

    Most endpoints return JSON; errors follow RFC 9457 problem

    documents on `application/problem+json`.


    Each plan has a per-minute, per-day and per-month request limit and

    a page size limit; `/v3/whoami` shows the limits of your plan. See

    https://api.datocapital.com/docs/entitlements.'
  contact:
    name: DatoCapital
    url: https://datocapital.com
servers:
- url: https://api.datocapital.com
  description: Production
security:
- bearer: []
tags:
- name: Companies
  description: Look up and search company records.
paths:
  /v3/companies:
    get:
      tags:
      - Companies
      summary: List or search companies
      description: 'Two paths:

        - **Filter mode** when `q` is absent: filter by `country`,

        `company_number`, `company_type_code`, `status`, `superseded`,

        `incorporation_from`/`incorporation_to`, geo (`near`/`bbox`),

        paginated by name.

        - **Search mode** when `q` is present: full-text on

        company name, optional `country` filter, ranked by score.'
      parameters:
      - name: q
        in: query
        schema:
          type: string
        description: Full-text query. 2-200 chars.
      - name: country
        in: query
        schema:
          type: string
          pattern: ^[A-Za-z]{2}$
      - name: company_number
        in: query
        schema:
          type: string
        description: SQL mode only.
      - name: company_number_secondary
        in: query
        schema:
          type: string
        description: SQL mode only.
      - name: company_type_code
        in: query
        schema:
          type: string
        description: SQL mode only.
      - name: status
        in: query
        schema:
          type: string
          enum:
          - open
          - closed
        description: SQL mode only.
      - name: superseded
        in: query
        schema:
          type: boolean
        description: SQL mode only.
      - name: incorporation_from
        in: query
        schema:
          type: string
          format: date
        description: SQL mode only.
      - name: incorporation_to
        in: query
        schema:
          type: string
          format: date
        description: SQL mode only.
      - name: near
        in: query
        schema:
          type: string
        description: lat,lon center for radius search (SQL mode).
      - name: radius
        in: query
        schema:
          type: number
        description: Required with `near`.
      - name: radius_unit
        in: query
        schema:
          type: string
          enum:
          - m
          - km
          - mi
          default: m
      - name: bbox
        in: query
        schema:
          type: string
        description: minLon,minLat,maxLon,maxLat (GeoJSON order). Max 5° per side.
      - name: language
        in: query
        schema:
          type: string
          enum:
          - en
          - es
          - fr
          - nl
          default: en
        description: Localised label resolution for status.
      - $ref: '#/components/parameters/pageSize'
      - $ref: '#/components/parameters/cursor'
      responses:
        '200':
          description: ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompanyList'
        '400':
          $ref: '#/components/responses/ValidationFailed'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/PlanInsufficient'
        '429':
          $ref: '#/components/responses/RateLimited'
      operationId: getV3Companies
      x-operation-id-source: derived
  /v3/companies/{uec}:
    get:
      tags:
      - Companies
      summary: Single company profile
      parameters:
      - name: uec
        in: path
        required: true
        schema:
          type: string
          pattern: ^\d{1,19}$
      - name: language
        in: query
        schema:
          type: string
          enum:
          - en
          - es
          - fr
          - nl
          default: en
      - name: expand
        in: query
        schema:
          type: string
        description: 'Comma-separated related data to embed. Supported: `filings` (first page, newest first; continue at the sub-resource URL). Unknown values return 400.'
      responses:
        '200':
          description: ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Company'
        '404':
          $ref: '#/components/responses/NotFound'
      operationId: getV3CompaniesByUec
      x-operation-id-source: derived
  /v3/companies/{uec}/representatives:
    get:
      tags:
      - Companies
      summary: Officers of a company (directors, secretaries, auditors, liquidators)
      description: 'One item for each role of each officer. The officer (`holder`) is a person (`type: individual`, with a link to the individual profile) or a company (`type: company`, with a link to the company profile). Current roles come first, then former roles, each newest first. Includes the officers recorded under the company''s former names.'
      parameters:
      - name: uec
        in: path
        required: true
        schema:
          type: string
          pattern: ^\d{1,19}$
      - name: status
        in: query
        schema:
          type: string
          enum:
          - current
          - former
          - all
          default: all
      - name: language
        in: query
        schema:
          type: string
          enum:
          - en
          - es
          default: en
        description: Language of `role.name`.
      - $ref: '#/components/parameters/pageSize'
      - $ref: '#/components/parameters/cursor'
      responses:
        '200':
          description: ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RepresentativeList'
        '400':
          $ref: '#/components/responses/ValidationFailed'
        '404':
          $ref: '#/components/responses/NotFound'
      operationId: getV3CompaniesByUecRepresentatives
      x-operation-id-source: derived
  /v3/{country}/{company_number}:
    get:
      tags:
      - Companies
      summary: Resolve (country, registry id) to canonical UEC profile
      description: 302 redirects to `/v3/companies/{uec}` when a current public match exists.
      parameters:
      - name: country
        in: path
        required: true
        schema:
          type: string
          pattern: ^[A-Za-z]{2}$
      - name: company_number
        in: path
        required: true
        schema:
          type: string
          pattern: ^[A-Za-z0-9.-]{1,64}$
      responses:
        '302':
          description: Found — Location header points at /v3/companies/{uec}
          headers:
            Location:
              schema:
                type: string
        '404':
          $ref: '#/components/responses/NotFound'
      operationId: getV3ByCountryByCompanyNumber
      x-operation-id-source: derived
components:
  schemas:
    Company:
      type: object
      properties:
        uec:
          type: string
          example: '9243433317131893'
        name:
          type: string
        name_original:
          type: string
        name_commercial:
          type: string
        country:
          type: string
        country_of_origin:
          type: string
        company_number:
          type: string
        company_number_secondary:
          type: string
        incorporation_date:
          type: string
          format: date
        published_on:
          type: string
          format: date
        dissolution_date:
          type: string
          format: date
        company_type:
          $ref: '#/components/schemas/CompanyType'
        status:
          $ref: '#/components/schemas/CompanyStatus'
        registered_address:
          $ref: '#/components/schemas/Address'
        website:
          type: string
        principal_activity:
          type: string
        corporate_purpose:
          type: string
        subscribed_capital:
          type: number
        paid_in_capital:
          type: number
        superseded_by:
          $ref: '#/components/schemas/Supersession'
        url:
          type: string
        representatives_url:
          type: string
        filings_url:
          type: string
        connections_url:
          type: string
        sources_url:
          type: string
    Problem:
      type: object
      properties:
        type:
          type: string
          format: uri
        title:
          type: string
        status:
          type: integer
        detail:
          type: string
        instance:
          type: string
        request_id:
          type: string
    CompanyType:
      type: object
      properties:
        id:
          type: string
          example: '0'
        code:
          type: string
          example: SL
        name_local:
          type: string
          example: SOCIEDAD LIMITADA
        country:
          type: string
          example: ES
    Supersession:
      type: object
      properties:
        uec:
          type: string
        reason:
          type: string
          enum:
          - name_change
          - address_change
          - duplicate_name
          - transformation
          - dissolution
          - extinction
          - different_company_number
        url:
          type: string
    CompanyList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Company'
        next_cursor:
          type: string
          nullable: true
        has_more:
          type: boolean
        total_estimate:
          type: integer
          description: Search-mode only (when `q` is set).
    Address:
      type: object
      properties:
        line1:
          type: string
        line2:
          type: string
        postal_code:
          type: string
        city:
          type: string
        region:
          type: string
        country:
          type: string
          example: ES
        latitude:
          type: number
        longitude:
          type: number
    RepresentativeList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Representative'
        next_cursor:
          type: string
          nullable: true
        has_more:
          type: boolean
    CompanyStatus:
      type: object
      properties:
        id:
          type: string
          example: '1'
        name_local:
          type: string
          example: Active
        is_closed:
          type: boolean
    Representative:
      type: object
      properties:
        holder:
          type: object
          properties:
            type:
              type: string
              enum:
              - individual
              - company
            name:
              type: string
            id:
              type: string
              description: Individual id, when the person has a profile.
            uec:
              type: string
              description: Company UEC, when the officer is a company with a profile.
            url:
              type: string
        role:
          type: object
          properties:
            name:
              type: string
              description: Role in the requested language, else as the register shows it.
            name_local:
              type: string
              description: Role as the register shows it.
        appointed_on:
          type: string
          format: date
          description: Absent when the source shows the end of the role only.
        ceased_on:
          type: string
          format: date
          description: Absent while the role is current.
        is_current:
          type: boolean
  responses:
    PlanInsufficient:
      description: 403 — endpoint requires a higher plan. `X-Required-Plan` header carries the unlock plan.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
      headers:
        X-Required-Plan:
          schema:
            type: string
    NotFound:
      description: 404 — id is unknown to the public surface.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    ValidationFailed:
      description: 400 — bad parameter shape or value.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    Unauthorized:
      description: 401 — missing or invalid bearer token.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    RateLimited:
      description: 429 — the per-minute, per-day or per-month limit of your plan is reached. `Retry-After` in seconds.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
      headers:
        Retry-After:
          schema:
            type: integer
        X-RateLimit-Limit:
          schema:
            type: integer
        X-RateLimit-Remaining:
          schema:
            type: integer
        X-RateLimit-Reset:
          schema:
            type: integer
        X-RateLimit-Limit-Day:
          schema:
            type: integer
        X-RateLimit-Remaining-Day:
          schema:
            type: integer
        X-RateLimit-Limit-Month:
          schema:
            type: integer
        X-RateLimit-Remaining-Month:
          schema:
            type: integer
  parameters:
    pageSize:
      name: page_size
      in: query
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 25
      description: 'Items per page. A value above your plan''s page size (`max_page_size` in `/v3/whoami`: free 25, starter 50, pro 100) is reduced to that size; `next_cursor` continues from the last item.'
    cursor:
      name: cursor
      in: query
      schema:
        type: string
      description: Opaque token taken from a prior response's `next_cursor`.
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
      bearerFormat: opaque
      description: 'DatoCapital API key. Format `dc_live_…` or `dc_test_…`. See

        the [Authentication guide](/docs/authentication).

        '