> ## Documentation Index
> Fetch the complete documentation index at: https://docs.syrto.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Struttura societaria

> I titolari effettivi sono calcolati dalle catene di partecipazione. Prezzo: 35 crediti per persona giuridica restituita; le voci notFound sono gratuite. Di sola lettura e idempotente: si usa POST solo perché la richiesta ha un corpo. Il metodo HTTP QUERY è il verbo preferito per questa operazione e verrà accettato sullo stesso percorso quando il supporto dei client sarà diffuso.



## OpenAPI

````yaml api-reference/openapi.standard.it.json POST /companies/structure
openapi: 3.1.0
info:
  title: Syrto API - endpoint standard
  version: 1.7.0
  description: >-
    Dati finanziari, societari e di mercato sulle aziende italiane.


    Ogni chiamata risponde `200 { data, meta }`; `meta.usage.quantity` è quanto
    ha consumato la

    chiamata, in crediti, e `meta.warnings` elenca eventuali avvertenze non
    bloccanti (vuoto quando non

    ce ne sono). Ogni campo è sempre presente e i valori sconosciuti sono null.
    Le percentuali sono

    frazioni (0,15 = 15%).


    **Autenticazione.** Ogni chiamata richiede una chiave API, inviata come
    `Authorization: Bearer sk_...`

    su HTTPS - mai in un URL. Le chiavi sono legate alla tua organizzazione: gli
    admin le creano e le

    revocano nella dashboard Syrto (https://dashboard.syrto.ai/api-keys). Una
    chiave mancante o non

    riconosciuta è un 401 (`missing_api_key`, `invalid_api_key`); un 503
    `auth_unavailable` significa

    che in questo momento non è stato possibile verificare la chiave, quindi
    riprova con backoff invece di

    ruotarla.


    **Base di addebito.** negativities, rna e structure addebitano una volta per
    persona giuridica: il

    record individuale e quello consolidato della stessa azienda contano una
    volta. Ogni altro endpoint

    addebita per record (o per chiamata), quindi individuale e consolidato
    contano separatamente. Un

    codice fiscale si risolve sempre in un solo record (`statementBasis`,
    individuale per impostazione

    predefinita): un'azienda viene addebitata due volte solo se vengono passati
    entrambi i suoi

    companyId. Una chiamata di mercato ha un prezzo per chiamata, qualunque sia
    la dimensione

    dell'insieme: omettere `filters` e `seedId`, o inviare `filters: {}`,
    significa tutta l'Italia, allo

    stesso prezzo. Le voci notFound non vengono mai addebitate, e nemmeno alcun
    errore.
servers:
  - url: https://api.syrto.ai
security: []
tags:
  - name: Company data
    description: Identità, indicatori di rischio, aiuti di Stato e sedi di aziende note.
  - name: Governance
    description: Proprietà, dirigenti, titolari effettivi e gruppo.
  - name: Financials
    description: Voci di bilancio, bilanci riclassificati, indici e grafico spider.
  - name: Composite
    description: Aziende comparabili.
  - name: Search
    description: Le aziende di un insieme filtrato, riga per riga.
  - name: Market
    description: Aggregati su un insieme filtrato.
  - name: Catalog
    description: Dati di riferimento gratuiti.
paths:
  /companies/structure:
    post:
      tags:
        - Governance
      summary: Proprietà, dirigenti, titolari effettivi e gruppo di fino a 20 aziende.
      description: >-
        I titolari effettivi sono calcolati dalle catene di partecipazione.
        Prezzo: 35 crediti per persona giuridica restituita; le voci notFound
        sono gratuite. Di sola lettura e idempotente: si usa POST solo perché la
        richiesta ha un corpo. Il metodo HTTP QUERY è il verbo preferito per
        questa operazione e verrà accettato sullo stesso percorso quando il
        supporto dei client sarà diffuso.
      operationId: company-structure
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                ids:
                  type: array
                  items:
                    type: string
                    minLength: 1
                    maxLength: 100
                  minItems: 1
                  maxItems: 20
                  description: >-
                    Da 1 a 20 riferimenti, ciascuno un companyId (id Syrto di un
                    record di bilancio, inizia con `Zm86`) o un codice fiscale
                    (partita IVA di 11 cifre o codice fiscale di 16 caratteri).
                    Un codice fiscale si risolve nel record selezionato da
                    `statementBasis`. I duplicati sono rifiutati.
                  example:
                    - '02579690039'
                    - '03841740016'
                roleCategories:
                  type: array
                  items:
                    $ref: '#/components/schemas/RoleCategory'
                  minItems: 1
                  maxItems: 9
                  description: >-
                    Restituisce solo i dirigenti con un ruolo in queste
                    categorie.
                language:
                  type: string
                  enum:
                    - it
                    - en
                  description: >-
                    Lingua di nomi, etichette e descrizioni delle metriche (mai
                    dei nomi dei campi o degli slug). Omessa: la lingua
                    predefinita dell'account.
              required:
                - ids
              additionalProperties: false
      responses:
        '200':
          description: >-
            Proprietà, dirigenti, titolari effettivi e gruppo di fino a 20
            aziende.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/CompanyStructureBatch'
                  meta:
                    $ref: '#/components/schemas/ResponseMeta'
                required:
                  - data
                  - meta
        '401':
          description: missing_api_key | invalid_api_key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '402':
          description: credits_exhausted | limit_reached
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: client_not_configured | not_entitled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: unknown_endpoint | not_found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '413':
          description: payload_too_large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '415':
          description: unsupported_media_type
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: invalid_params
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: rate_limited
          headers:
            Retry-After:
              description: >-
                Secondi da attendere prima di riprovare. Né un 429 né un 504
                vengono addebitati. Un 504 la cui query aveva raggiunto il
                servizio dati lo lascia in esecuzione, e la sua risposta viene
                messa in cache, quindi la stessa chiamata dopo questo intervallo
                è di solito veloce.
              schema:
                type: integer
                minimum: 0
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: internal_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '502':
          description: upstream_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: auth_unavailable | entitlement_unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '504':
          description: upstream_timeout
          headers:
            Retry-After:
              description: >-
                Secondi da attendere prima di riprovare. Né un 429 né un 504
                vengono addebitati. Un 504 la cui query aveva raggiunto il
                servizio dati lo lascia in esecuzione, e la sua risposta viene
                messa in cache, quindi la stessa chiamata dopo questo intervallo
                è di solito veloce.
              schema:
                type: integer
                minimum: 0
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - bearerAuth: []
components:
  schemas:
    RoleCategory:
      type: string
      enum:
        - GOVERNING_BODIES
        - ADMINISTRATION_AND_EXECUTIVES
        - AUDITING
        - REPRESENTATION_AND_AUTHORITY
        - EXTRAORDINARY_PROCEDURES
        - FUNCTIONAL_ROLES
        - PARTICIPATION_OWNERSHIP
        - CHIEF_EXECUTIVE_OFFICER
        - OTHER
    CompanyStructureBatch:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/CompanyStructure'
          description: Voci risolte, nell'ordine di input.
        notFound:
          type: array
          items:
            $ref: '#/components/schemas/NotFoundEntry'
      required:
        - items
        - notFound
    ResponseMeta:
      type: object
      properties:
        requestId:
          type: string
        endpoint:
          type: string
        usage:
          $ref: '#/components/schemas/Usage'
        warnings:
          type: array
          items:
            $ref: '#/components/schemas/Warning'
          description: Vuoto quando non ce ne sono.
      required:
        - requestId
        - endpoint
        - usage
        - warnings
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              enum:
                - missing_api_key
                - invalid_api_key
                - credits_exhausted
                - limit_reached
                - client_not_configured
                - not_entitled
                - unknown_endpoint
                - not_found
                - payload_too_large
                - unsupported_media_type
                - invalid_params
                - rate_limited
                - internal_error
                - upstream_error
                - auth_unavailable
                - entitlement_unavailable
                - upstream_timeout
            message:
              type: string
            requestId:
              type: string
            details:
              type: array
              items:
                type: object
                properties:
                  path:
                    type: string
                  message:
                    type: string
                required:
                  - path
                  - message
          required:
            - code
            - message
            - requestId
      required:
        - error
    CompanyStructure:
      allOf:
        - $ref: '#/components/schemas/CompanyHeader'
        - type: object
          properties:
            controllingEntityCategory:
              anyOf:
                - $ref: '#/components/schemas/ControllingEntityCategory'
                - type: 'null'
            isForeignOwned:
              type:
                - boolean
                - 'null'
            isQuoted:
              type:
                - boolean
                - 'null'
            officers:
              $ref: '#/components/schemas/OfficerList'
            shareholders:
              $ref: '#/components/schemas/ShareholderList'
            beneficialOwners:
              $ref: '#/components/schemas/BeneficialOwnerList'
            subsidiaries:
              $ref: '#/components/schemas/SubsidiaryList'
            linkedCompanies:
              $ref: '#/components/schemas/LinkedCompanyList'
            companiesWithSharedOfficers:
              $ref: '#/components/schemas/SharedOfficerCompanyList'
          required:
            - controllingEntityCategory
            - isForeignOwned
            - isQuoted
            - officers
            - shareholders
            - beneficialOwners
            - subsidiaries
            - linkedCompanies
            - companiesWithSharedOfficers
      description: >-
        Le liste contengono fino a 100 voci per una singola azienda e 10 in una
        chiamata su più aziende; chiama una holding da sola per ottenerne di
        più.
    NotFoundEntry:
      type: object
      properties:
        position:
          type: integer
          minimum: 0
          description: Posizione nell'array `ids`.
        input:
          type: string
        reason:
          type: string
          enum:
            - not_found
            - no_filing_for_year
            - invalid_id
      required:
        - position
        - input
        - reason
      description: Un id che non è stato risolto. Mai addebitato.
    Usage:
      type: object
      properties:
        quantity:
          type: number
        unit:
          type: string
      required:
        - quantity
        - unit
    Warning:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
      required:
        - code
        - message
    CompanyHeader:
      type: object
      properties:
        companyId:
          type: string
          description: >-
            Id Syrto di questo record di bilancio. Individuale e consolidato
            differiscono.
        legalName:
          type:
            - string
            - 'null'
        taxId:
          type:
            - string
            - 'null'
          description: Codice fiscale / partita IVA.
        consolidated:
          type: boolean
          description: >-
            Indica se questi valori provengono dal bilancio consolidato (di
            gruppo).
      required:
        - companyId
        - legalName
        - taxId
        - consolidated
    ControllingEntityCategory:
      type: string
      enum:
        - FAMILY
        - FAMILY_OWNED_GROUP
        - FINANCIALLY_OWNED_GROUP
        - INDUSTRIAL_GROUP
        - FINANCIAL
        - OTHER
    OfficerList:
      type: object
      properties:
        total:
          type:
            - integer
            - 'null'
          description: Conta i RUOLI; una persona può averne più di uno.
        peopleTotal:
          type:
            - integer
            - 'null'
          description: Conta le persone distinte; null quando la lista è troncata.
        truncated:
          type: boolean
          description: True quando `items` è più corto di `total`.
        items:
          type: array
          items:
            $ref: '#/components/schemas/Officer'
      required:
        - total
        - peopleTotal
        - truncated
        - items
    ShareholderList:
      type: object
      properties:
        total:
          type:
            - integer
            - 'null'
        truncated:
          type: boolean
          description: True quando `items` è più corto di `total`.
        items:
          type: array
          items:
            $ref: '#/components/schemas/Holder'
      required:
        - total
        - truncated
        - items
    BeneficialOwnerList:
      type: object
      properties:
        total:
          type:
            - integer
            - 'null'
        truncated:
          type: boolean
          description: True quando `items` è più corto di `total`.
        items:
          type: array
          items:
            $ref: '#/components/schemas/BeneficialOwner'
      required:
        - total
        - truncated
        - items
    SubsidiaryList:
      type: object
      properties:
        total:
          type:
            - integer
            - 'null'
        truncated:
          type: boolean
          description: True quando `items` è più corto di `total`.
        items:
          type: array
          items:
            $ref: '#/components/schemas/Holder'
      required:
        - total
        - truncated
        - items
    LinkedCompanyList:
      type: object
      properties:
        total:
          type:
            - integer
            - 'null'
        truncated:
          type: boolean
          description: True quando `items` è più corto di `total`.
        items:
          type: array
          items:
            $ref: '#/components/schemas/StructureEntity'
      required:
        - total
        - truncated
        - items
    SharedOfficerCompanyList:
      type: object
      properties:
        total:
          type:
            - integer
            - 'null'
          description: 'Sempre null: il registro non espone un conteggio.'
        truncated:
          type: boolean
          description: True quando `items` è più corto di `total`.
        items:
          type: array
          items:
            $ref: '#/components/schemas/StructureEntity'
      required:
        - total
        - truncated
        - items
    Officer:
      allOf:
        - $ref: '#/components/schemas/StructureEntity'
        - type: object
          properties:
            roles:
              type: array
              items:
                $ref: '#/components/schemas/OfficerRole'
          required:
            - roles
      description: Una persona, un'azienda o un'entità non classificata.
    Holder:
      allOf:
        - $ref: '#/components/schemas/StructureEntity'
        - type: object
          properties:
            share:
              type:
                - number
                - 'null'
              description: Quota di proprietà, frazione (0,51).
          required:
            - share
      description: Una persona, un'azienda o un'entità non classificata.
    BeneficialOwner:
      allOf:
        - $ref: '#/components/schemas/Holder'
        - type: object
          properties:
            ownershipChains:
              type: array
              items:
                type: array
                items:
                  $ref: '#/components/schemas/Holder'
              description: >-
                Catene di controllo dall'azienda al titolare, a partire
                dall'anello più vicino.
          required:
            - ownershipChains
      description: Una persona, un'azienda o un'entità non classificata.
    StructureEntity:
      type: object
      properties:
        entityType:
          type: string
          enum:
            - person
            - company
            - unclassified
        name:
          type:
            - string
            - 'null'
        personId:
          type:
            - string
            - 'null'
          description: Id della persona (utilizzabile nei filtri di ricerca).
        age:
          type:
            - integer
            - 'null'
          description: Età della persona, in anni.
        companyId:
          type:
            - string
            - 'null'
        taxId:
          type:
            - string
            - 'null'
      required:
        - entityType
        - name
        - personId
        - age
        - companyId
        - taxId
      description: Una persona, un'azienda o un'entità non classificata.
    OfficerRole:
      type: object
      properties:
        roleCategory:
          $ref: '#/components/schemas/RoleCategory'
        role:
          type:
            - string
            - 'null'
      required:
        - roleCategory
        - role
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Chiave API di organizzazione WorkOS (sk_...), inviata come
        `Authorization: Bearer <key>`. Gli admin creano e revocano le chiavi
        nella dashboard Syrto: https://dashboard.syrto.ai/api-keys

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.