openapi: 3.0.3
info:
  title: Firmium API
  version: v1
paths:
  /api/v1/companies/{uuid}/:
    get:
      operationId: get_company
      description: Retrieve basic company information including name, status, legal
        form, VAT number, registration number, and addresses.
      summary: Get company profile
      parameters:
      - in: path
        name: uuid
        schema:
          type: string
          format: uuid
        required: true
      tags:
      - v1
      security:
      - cookieAuth: []
      - SessionAuth: []
      - TokenAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompanyBaseDataset'
          description: ''
        '404':
          content:
            application/json:
              schema:
                description: Company not found
          description: ''
  /api/v1/companies/search/:
    post:
      operationId: search_companies
      description: Search for companies by name and/or registration number. Use 'country'
        to filter by country code (AT, DE, CH, etc.).
      summary: Search companies
      parameters:
      - in: query
        name: euid
        schema:
          type: string
      - in: query
        name: legal_form
        schema:
          type: string
      - in: query
        name: name
        schema:
          type: string
      - name: page
        required: false
        in: query
        description: A page number within the paginated result set.
        schema:
          type: integer
      - in: query
        name: registration_number
        schema:
          type: string
      - in: query
        name: status
        schema:
          type: string
          enum:
          - Active
          - Bankrupt
          - Dissolved
          - In Liquidation
          - Inactive
          - Insolvency Proceeding
          - Relocated
          - Restructuring
        description: |-
          * `Active` - Active
          * `Inactive` - Inactive
          * `In Liquidation` - In Liquidation
          * `Dissolved` - Dissolved
          * `Bankrupt` - Bankrupt
          * `Restructuring` - Restructuring
          * `Insolvency Proceeding` - Insolvency Proceeding
          * `Relocated` - Relocated
      - in: query
        name: vat_number
        schema:
          type: string
      tags:
      - v1
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CompanySearch'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/CompanySearch'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/CompanySearch'
        required: true
      security:
      - cookieAuth: []
      - SessionAuth: []
      - TokenAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedCompanySearchList'
          description: ''
        '400':
          content:
            application/json:
              schema:
                description: Invalid search parameters
          description: ''
components:
  schemas:
    Address:
      type: object
      description: Serializer for company addresses
      properties:
        street:
          type: string
          maxLength: 255
        house_number:
          type: string
          maxLength: 20
        city:
          type: string
          maxLength: 100
        postal_code:
          type: string
          maxLength: 20
        country:
          type: string
          maxLength: 100
        country_code:
          type: string
          maxLength: 3
        is_primary:
          type: boolean
        latitude:
          type: string
          format: decimal
          pattern: ^-?\d{0,3}(?:\.\d{0,7})?$
          nullable: true
        longitude:
          type: string
          format: decimal
          pattern: ^-?\d{0,3}(?:\.\d{0,7})?$
          nullable: true
    CompanyBaseDataset:
      type: object
      description: Serializer for company base dataset
      properties:
        uuid:
          type: string
          format: uuid
          readOnly: true
        name:
          type: string
          maxLength: 512
        status:
          $ref: '#/components/schemas/StatusEnum'
        legal_form:
          type: string
          nullable: true
          maxLength: 255
        vat_number:
          type: string
          nullable: true
          maxLength: 50
        registration_number:
          type: string
          description: Local registry number
          maxLength: 100
        addresses:
          type: array
          items:
            $ref: '#/components/schemas/Address'
          readOnly: true
        industry_codes:
          type: array
          items:
            $ref: '#/components/schemas/IndustryClassification'
          readOnly: true
      required:
      - addresses
      - industry_codes
      - name
      - registration_number
      - uuid
    CompanySearch:
      type: object
      description: Serializer for company search
      properties:
        uuid:
          type: string
          format: uuid
          readOnly: true
        name:
          type: string
          maxLength: 512
        registration_number:
          type: string
          description: Local registry number
          maxLength: 100
        country:
          type: string
          readOnly: true
        status:
          $ref: '#/components/schemas/StatusEnum'
      required:
      - country
      - name
      - uuid
    IndustryClassification:
      type: object
      description: |-
        Serializer for a company's industry classification (NACE/WZ/SIC/ÖNACE/...).

        `code`/`description`/`scheme`/`version` come from the related industry
        code, not from this model directly.
      properties:
        code:
          type: string
          readOnly: true
          nullable: true
        description:
          type: string
          readOnly: true
          nullable: true
        scheme:
          type: string
          readOnly: true
          nullable: true
        version:
          type: string
          readOnly: true
          nullable: true
        is_primary:
          type: boolean
          description: Indicates if this is the primary classification
      required:
      - code
      - description
      - scheme
      - version
    PaginatedCompanySearchList:
      type: object
      required:
      - count
      - results
      properties:
        count:
          type: integer
          example: 123
        next:
          type: string
          nullable: true
          format: uri
          example: http://api.example.org/accounts/?page=4
        previous:
          type: string
          nullable: true
          format: uri
          example: http://api.example.org/accounts/?page=2
        results:
          type: array
          items:
            $ref: '#/components/schemas/CompanySearch'
    StatusEnum:
      enum:
      - Active
      - Inactive
      - In Liquidation
      - Dissolved
      - Bankrupt
      - Restructuring
      - Insolvency Proceeding
      - Relocated
      type: string
      description: |-
        * `Active` - Active
        * `Inactive` - Inactive
        * `In Liquidation` - In Liquidation
        * `Dissolved` - Dissolved
        * `Bankrupt` - Bankrupt
        * `Restructuring` - Restructuring
        * `Insolvency Proceeding` - Insolvency Proceeding
        * `Relocated` - Relocated
  securitySchemes:
    SessionAuth:
      type: apiKey
      in: header
      name: Authorization
      description: 'Session authentication. Formats: Authorization: Session <sessionid>
        | Query: ?sessionid=<key> | Cookie: sessionid=<key>'
    TokenAuth:
      type: apiKey
      in: header
      name: Authorization
      description: 'Token authentication. Format: Token <key>'
    cookieAuth:
      type: apiKey
      in: cookie
      name: sessionid
servers:
- url: https://www.firmium.de/
tags:
- name: v1
  description: Company and business data endpoints