openapi: 3.0.3
info:
  title: i2 group API
  version: 2.0.0
  license:
    name: Proprietary
    url: https://www.mnai.tech/terms-and-conditions/
  description: >
    # Summary

    API for searching companies and people, retrieving full details, and
    exploring their network connections.


    # Quota

    Each API key is limited based on credits. If you run out of credits, you
    will receive a `429 Too Many Requests` response.


    # Authentication

    You must provide an API key in the `i2-api-key` header to access the API. If
    you do not provide a valid API key, you will receive a `401 Unauthorized`
    response.
servers:
  - url: https://dev-api-gateway.mnai.tech/i2-group
  - url: https://prod-api-gateway.mnai.tech/i2-group
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: i2-api-key
  responses:
    TooManyRequests:
      description: Too many requests.
      content:
        application/json:
          schema:
            type: object
            additionalProperties: false
            properties:
              message:
                type: string
          examples:
            RateLimitExceeded:
              summary: Request rate exceeded
              value:
                message: Rate limit exceeded. Please try again later.
            QuotaExceeded:
              summary: Quota limit reached
              value:
                message: Quota exceeded. Please contact support.
    Unauthorized:
      description: Invalid or missing API key.
      content:
        application/json:
          schema:
            type: object
            additionalProperties: false
            properties:
              message:
                type: string
          example:
            message: Invalid API key.
    NotFound:
      description: Resource not found.
      content:
        application/json:
          schema:
            type: object
            additionalProperties: false
            properties:
              message:
                type: string
          example:
            message: Record not found.
    BadRequest:
      description: Bad request.
      content:
        application/json:
          schema:
            type: object
            additionalProperties: false
            properties:
              message:
                type: string
          example:
            message: 'Invalid request: {reason}.'
    InternalServerError:
      description: Internal server error.
      content:
        application/json:
          schema:
            type: object
            additionalProperties: false
            properties:
              message:
                type: string
          example:
            message: Internal server error.
security:
  - ApiKeyAuth: []
paths:
  /company/search:
    get:
      summary: Search companies
      parameters:
        - name: searchText
          in: query
          required: false
          schema:
            type: string
            default: mnai
          description: |
            Company name or number. Not case-sensitive.
            You can provide either a company name or a company number here.
        - name: status
          in: query
          required: false
          schema:
            type: string
            enum:
              - Active
              - In distress
              - Closed
            default: Active
          description: company status one of Active, In distress, Closed.
      description: >
        The ability to search for a company by `company name` or `company
        number`.


        Results can be filtered by `status` (Active, In distress, Closed).


        Results are ordered by matching relevance.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  additionalProperties: false
                  required:
                    - idCompany
                    - profileLink
                    - name
                    - number
                    - companyStatus
                    - registerStatus
                    - score
                  properties:
                    idCompany:
                      type: integer
                      nullable: false
                    profileLink:
                      type: string
                      nullable: false
                    name:
                      type: string
                    number:
                      type: string
                      nullable: false
                    incorporatedDate:
                      type: string
                      format: date
                      pattern: ^\d{4}-\d{2}-\d{2}$
                      nullable: true
                    companyStatus:
                      type: string
                      nullable: false
                    registerStatus:
                      type: string
                      nullable: false
                    registeredAddress:
                      type: object
                      additionalProperties: false
                      properties:
                        line1:
                          type: string
                          nullable: true
                        line2:
                          type: string
                          nullable: true
                        line3:
                          type: string
                          nullable: true
                        line4:
                          type: string
                          nullable: true
                        town:
                          type: string
                          nullable: true
                        postcode:
                          type: string
                          nullable: true
                    historicalNames:
                      type: array
                      items:
                        type: object
                        additionalProperties: false
                        required:
                          - name
                          - fromDate
                          - toDate
                        properties:
                          name:
                            type: string
                            nullable: false
                          fromDate:
                            type: string
                            format: date
                            pattern: ^\d{4}-\d{2}-\d{2}$
                            nullable: false
                          toDate:
                            type: string
                            format: date
                            pattern: ^\d{4}-\d{2}-\d{2}$
                            nullable: false
                    score:
                      type: number
                      format: float
                      nullable: false
              example:
                - idCompany: 123
                  profileLink: https://platform.mnai.tech/company/123/summary
                  name: ABC Holdings Ltd
                  number: '12345678'
                  incorporatedDate: '2010-05-20'
                  companyStatus: Active
                  registerStatus: Active
                  registeredAddress:
                    line1: Flat 4
                    line2: 123 Main St
                    line3: null
                    line4: null
                    town: London
                    postcode: W1A 1AA
                  historicalNames:
                    - name: ABC Ltd
                      fromDate: '2010-05-20'
                      toDate: '2015-06-30'
                  score: 99.1
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /person/search:
    get:
      summary: Search people
      description: >
        The ability to search for a person by `name`, `company name` or `company
        number`.


        Results can be filtered by `birthDate` (format must be `YYYY-MM`).


        Results are ordered by matching relevance.
      parameters:
        - name: searchText
          in: query
          required: true
          schema:
            type: string
          description: Not case-sensitive.
        - name: birthDate
          in: query
          required: false
          schema:
            type: string
          description: format must be `YYYY-MM`
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  additionalProperties: false
                  required:
                    - idPerson
                    - profileLink
                    - name
                  properties:
                    idPerson:
                      type: integer
                      nullable: false
                    profileLink:
                      type: string
                      nullable: false
                    name:
                      type: string
                      nullable: false
                    birthDate:
                      type: string
                      pattern: ^\d{4}-\d{2}$
                      nullable: true
                    activeRoles:
                      type: array
                      items:
                        type: object
                        additionalProperties: false
                        properties:
                          companyName:
                            type: string
                            nullable: false
                          companyNumber:
                            type: string
                            nullable: false
                          idCompany:
                            type: integer
                            nullable: false
                    addresses:
                      type: array
                      items:
                        type: object
                        additionalProperties: false
                        properties:
                          line1:
                            type: string
                            nullable: true
                          line2:
                            type: string
                            nullable: true
                          line3:
                            type: string
                            nullable: true
                          line4:
                            type: string
                            nullable: true
                          town:
                            type: string
                            nullable: true
                          postcode:
                            type: string
                            nullable: true
                    score:
                      type: number
                      format: float
                      nullable: false
              example:
                - idPerson: 987
                  profileLink: https://platform.mnai.tech/person/987/summary
                  name: John Doe
                  birthDate: 1980-06
                  addresses:
                    - line1: 456 Another Rd
                      line2: null
                      line3: null
                      line4: null
                      town: Manchester
                      postcode: M1 2AB
                  score: 99.1
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /company/{idCompany}:
    get:
      summary: Company details
      description: |
        Retrieve full details of a company by `idCompany`.
      parameters:
        - name: idCompany
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                required:
                  - idCompany
                  - profileLink
                  - name
                  - number
                  - incorporatedDate
                  - companyStatus
                  - registerStatus
                  - description
                properties:
                  idCompany:
                    type: integer
                    nullable: false
                  profileLink:
                    type: string
                    nullable: false
                  name:
                    type: string
                    nullable: false
                  number:
                    type: string
                    nullable: false
                  incorporatedDate:
                    type: string
                    format: date
                    pattern: ^\d{4}-\d{2}-\d{2}$
                    nullable: true
                  companyStatus:
                    type: string
                    nullable: false
                  registerStatus:
                    type: string
                    nullable: false
                  description:
                    type: string
                    nullable: false
                  registeredAddress:
                    type: object
                    additionalProperties: false
                    properties:
                      line1:
                        type: string
                        nullable: true
                      line2:
                        type: string
                        nullable: true
                      line3:
                        type: string
                        nullable: true
                      line4:
                        type: string
                        nullable: true
                      town:
                        type: string
                        nullable: true
                      postcode:
                        type: string
                        nullable: true
                  vatNumbers:
                    type: array
                    items:
                      type: string
                      nullable: false
                  websites:
                    type: array
                    items:
                      type: string
                      nullable: false
                  socials:
                    type: array
                    items:
                      type: object
                      additionalProperties: false
                      properties:
                        platform:
                          type: string
                          nullable: false
                        linkUrl:
                          type: string
                          nullable: false
                  historicalNames:
                    type: array
                    items:
                      type: object
                      additionalProperties: false
                      properties:
                        name:
                          type: string
                          nullable: false
                        fromDate:
                          type: string
                          format: date
                          pattern: ^\d{4}-\d{2}-\d{2}$
                          nullable: false
                        toDate:
                          type: string
                          format: date
                          pattern: ^\d{4}-\d{2}-\d{2}$
                          nullable: false
                  historicalAddresses:
                    type: array
                    items:
                      type: object
                      additionalProperties: false
                      properties:
                        address:
                          type: string
                          nullable: false
                        fromDate:
                          type: string
                          format: date
                          pattern: ^\d{4}-\d{2}-\d{2}$
                          nullable: true
                        toDate:
                          type: string
                          format: date
                          pattern: ^\d{4}-\d{2}-\d{2}$
                          nullable: true
                  accounts:
                    type: object
                    additionalProperties: false
                    properties:
                      latestAccountsDate:
                        type: string
                        format: date
                        pattern: ^\d{4}-\d{2}-\d{2}$
                        nullable: true
                      latestTurnover:
                        type: number
                        format: float
                        nullable: true
                      latestNetAssets:
                        type: number
                        format: float
                        nullable: true
                      latestEmployees:
                        type: number
                        nullable: true
                      estimatedTurnover:
                        type: string
                        nullable: true
                  sicCodes:
                    type: array
                    items:
                      type: string
                      nullable: false
                  keywords:
                    type: array
                    items:
                      type: string
                      nullable: false
                  tags:
                    type: array
                    items:
                      type: string
                      nullable: false
                  impact:
                    type: object
                    additionalProperties: false
                    properties:
                      overallScore:
                        type: number
                        nullable: true
                      governanceScore:
                        type: number
                        nullable: true
                      emissionsScore:
                        type: number
                        nullable: true
                      diversityScore:
                        type: number
                        nullable: true
                      financialRiskScore:
                        type: number
                        nullable: true
                      sectorScore:
                        type: number
                        nullable: true
              example:
                idCompany: 123
                profileLink: https://platform.mnai.tech/company/123/summary
                name: ABC Holdings Ltd
                number: '12345678'
                incorporatedDate: '2010-05-20'
                companyStatus: Active
                registerStatus: Active
                description: Holding company for ABC Group.
                registeredAddress:
                  line1: Flat 4
                  line2: 123 Main St
                  line3: null
                  line4: null
                  town: London
                  postcode: W1A 1AA
                vatNumbers:
                  - GB123456789
                  - GB987654321
                websites:
                  - https://www.abcholdings.com
                  - https://www.abcgroup.com
                socials:
                  - platform: linkedin
                    linkUrl: https://www.linkedin.com/company/abcholdings
                  - platform: twitter
                    linkUrl: https://www.twitter.com/abcholdings
                  - platform: facebook
                    linkUrl: https://www.facebook.com/abcholdings
                  - platform: instagram
                    linkUrl: https://www.instagram.com/abcholdings
                  - platform: tiktok
                    linkUrl: https://www.tiktok.com/@abcholdings
                historicalNames:
                  - name: ABC Ltd
                    fromDate: '2010-05-20'
                    toDate: '2015-06-30'
                historicalAddresses:
                  - address: Flat 4, 123 Main St, London, W1A 1AA
                    fromDate: '2010-05-20'
                    toDate: '2015-06-30'
                accounts:
                  latestAccountsDate: '2021-12-31'
                  latestTurnover: 1234567
                  latestNetAssets: 987654
                  latestEmployees: 100
                  estimatedTurnover: £1m-£2m
                sicCodes:
                  - '12345'
                  - '54321'
                keywords:
                  - Holding Company
                  - Investment
                tags:
                  - Innovative company
                  - Has VC investment
                  - VAT registered
                impact:
                  overallScore: 600
                  governanceScore: 75
                  emissionsScore: 100
                  diversityScore: 91
                  financialRiskScore: 60
                  sectorScore: 66
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /person/{idPerson}:
    get:
      summary: Person details
      description: |
        Retrieve full details of a person by `idPerson`.
      parameters:
        - name: idPerson
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                required:
                  - idPerson
                  - profileLink
                  - name
                properties:
                  idPerson:
                    type: integer
                    nullable: false
                  profileLink:
                    type: string
                    nullable: false
                  name:
                    type: string
                    nullable: false
                  birthDate:
                    type: string
                    pattern: ^\d{4}-\d{2}$
                    nullable: true
                  nationality:
                    type: string
                    nullable: true
                  linkedin:
                    type: array
                    nullable: true
                    items:
                      type: string
                      nullable: false
                  impact:
                    type: object
                    additionalProperties: false
                    properties:
                      overallScore:
                        type: integer
                        nullable: true
                      governanceScore:
                        type: integer
                        nullable: true
                      emissionsScore:
                        type: integer
                        nullable: true
                      diversityScore:
                        type: integer
                        nullable: true
                      financialRiskScore:
                        type: integer
                        nullable: true
                      sectorScore:
                        type: integer
                        nullable: true
              example:
                idPerson: 789
                profileLink: https://platform.mnai.tech/person/789/summary
                name: John Doe
                birthDate: 1980-06
                nationality: British
                linkedin:
                  - https://www.linkedin.com/in/johndoe
                impact:
                  overallScore: 600
                  governanceScore: 75
                  emissionsScore: 100
                  diversityScore: 91
                  financialRiskScore: 60
                  sectorScore: 66
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /person/{idPerson}/addresses:
    get:
      summary: Person addresses
      description: |
        Retrieve addresses of a person by `idPerson`.

        Results are ordered by `companyStatus`.
      parameters:
        - name: idPerson
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  additionalProperties: false
                  required:
                    - idCompany
                    - profileLink
                    - companyName
                    - companyNumber
                    - registerStatus
                    - companyStatus
                  properties:
                    idCompany:
                      type: integer
                      nullable: false
                    profileLink:
                      type: string
                      nullable: false
                    companyName:
                      type: string
                      nullable: false
                    companyNumber:
                      type: string
                      nullable: false
                    incorporatedDate:
                      type: string
                      format: date
                      pattern: ^\d{4}-\d{2}-\d{2}$
                      nullable: true
                    registerStatus:
                      type: string
                      nullable: false
                    companyStatus:
                      type: string
                      nullable: false
                    line1:
                      type: string
                      nullable: true
                    line2:
                      type: string
                      nullable: true
                    line3:
                      type: string
                      nullable: true
                    line4:
                      type: string
                      nullable: true
                    town:
                      type: string
                      nullable: true
                    postcode:
                      type: string
                      nullable: true
              example:
                - idCompany: 123
                  profileLink: https://platform.mnai.tech/company/123/summary
                  companyName: ABC Holdings Ltd
                  companyNumber: '12345678'
                  incorporatedDate: '2020-01-01'
                  registerStatus: Active
                  companyStatus: Active
                  line1: 456 Another Rd
                  line2: null
                  line3: null
                  line4: null
                  town: Manchester
                  postcode: M1 2AB
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /person/{idPerson}/roles:
    get:
      summary: Person roles
      description: |
        Retrieve role details of a person by `idPerson`.

        Results are ordered by `appointedDate` DESC.
      parameters:
        - name: idPerson
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  additionalProperties: false
                  required:
                    - idCompany
                    - profileLink
                    - number
                    - name
                    - companyStatus
                    - registerStatus
                    - role
                    - appointedDate
                  properties:
                    idCompany:
                      type: integer
                      nullable: false
                    profileLink:
                      type: string
                      nullable: false
                    number:
                      type: string
                      nullable: false
                    name:
                      type: string
                      nullable: false
                    incorporatedDate:
                      type: string
                      format: date
                      pattern: ^\d{4}-\d{2}-\d{2}$
                      nullable: true
                    companyStatus:
                      type: string
                      nullable: false
                    registerStatus:
                      type: string
                      nullable: false
                    role:
                      type: string
                      nullable: false
                    appointedDate:
                      type: string
                      format: date
                      pattern: ^\d{4}-\d{2}-\d{2}$
                      nullable: false
                    resignedDate:
                      type: string
                      format: date
                      pattern: ^\d{4}-\d{2}-\d{2}$
                      nullable: true
              example:
                - idCompany: 123
                  profileLink: https://platform.mnai.tech/company/123/summary
                  number: '12345678'
                  name: ABC Holdings Ltd
                  incorporatedDate: '2010-05-20'
                  companyStatus: Active
                  registerStatus: Active
                  role: Director
                  appointedDate: '2010-05-20'
                  resignedDate: null
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /person/{idPerson}/shareholdings:
    get:
      summary: Person shareholdings
      description: |
        Retrieve shareholdings of a person by `idPerson`.

        Results are ordered by `sharesSince` DESC.
      parameters:
        - name: idPerson
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  additionalProperties: false
                  required:
                    - idCompany
                    - profileLink
                    - number
                    - name
                    - companyStatus
                    - registerStatus
                    - shares
                    - percentage
                  properties:
                    idCompany:
                      type: integer
                      nullable: false
                    profileLink:
                      type: string
                      nullable: false
                    number:
                      type: string
                      nullable: false
                    name:
                      type: string
                      nullable: false
                    incorporatedDate:
                      type: string
                      format: date
                      pattern: ^\d{4}-\d{2}-\d{2}$
                      nullable: true
                    companyStatus:
                      type: string
                      nullable: false
                    registerStatus:
                      type: string
                      nullable: false
                    shares:
                      type: integer
                      nullable: false
                    sharesSince:
                      type: string
                      format: date
                      pattern: ^\d{4}-\d{2}-\d{2}$
                      nullable: true
                    sharesUntil:
                      type: string
                      format: date
                      pattern: ^\d{4}-\d{2}-\d{2}$
                      nullable: true
                    percentage:
                      type: number
                      format: float
                      minimum: 0
                      maximum: 100
                      example: 25.5
                      nullable: false
              example:
                - idCompany: 123
                  profileLink: https://platform.mnai.tech/company/123/summary
                  number: '12345678'
                  name: ABC Holdings Ltd
                  incorporatedDate: '2010-05-20'
                  companyStatus: Active
                  registerStatus: Active
                  sharesSince: '2020-01-01'
                  sharesUntil: null
                  shares: 100
                  percentage: 12.34
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /company/{idCompany}/network:
    get:
      summary: Company network
      description: |
        Retrieve any linked connections of a company by `idCompany`.

        This can be used to explore or extend the network of a company.
      parameters:
        - name: idCompany
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                required:
                  - nodes
                  - relationships
                properties:
                  nodes:
                    type: array
                    items:
                      type: object
                      additionalProperties: false
                      required:
                        - idNode
                        - entityType
                        - name
                      properties:
                        idNode:
                          type: integer
                          nullable: false
                        entityType:
                          type: string
                          nullable: false
                        idPerson:
                          type: integer
                          nullable: true
                        idCompany:
                          type: integer
                          nullable: true
                        idOtherEntity:
                          type: integer
                          nullable: true
                        profileLink:
                          type: string
                          nullable: true
                        name:
                          type: string
                          nullable: false
                        number:
                          type: string
                          nullable: true
                  relationships:
                    type: array
                    items:
                      type: object
                      additionalProperties: false
                      required:
                        - sourceNode
                        - targetNode
                        - type
                      properties:
                        sourceNode:
                          type: integer
                          nullable: false
                        targetNode:
                          type: integer
                          nullable: false
                        type:
                          type: string
                          nullable: false
              example:
                nodes:
                  - entityType: person
                    idNode: 123
                    idPerson: 123
                    profileLink: https://platform.mnai.tech/person/123/summary
                    name: John Doe
                  - entityType: company
                    idNode: 456
                    idCompany: 456
                    profileLink: https://platform.mnai.tech/company/456/summary
                    name: ABC Holdings Ltd
                    number: '12345678'
                  - entityType: other
                    idNode: 789
                    name: ABC Holdings Inc
                relationships:
                  - sourceNode: 456
                    targetNode: 123
                    type: officer
                  - sourceNode: 456
                    targetNode: 123
                    type: shareholder
                  - sourceNode: 456
                    targetNode: 789
                    type: psc
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /person/{idPerson}/network:
    get:
      summary: Person network
      description: |
        Retrieve any linked connections of a person by `idPerson`.

        This can be used to explore or extend the network of a person.
      parameters:
        - name: idPerson
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                required:
                  - nodes
                  - relationships
                properties:
                  nodes:
                    type: array
                    items:
                      type: object
                      additionalProperties: false
                      required:
                        - idNode
                        - entityType
                        - name
                      properties:
                        idNode:
                          type: integer
                          nullable: false
                        entityType:
                          type: string
                          nullable: false
                        idPerson:
                          type: integer
                          nullable: true
                        idCompany:
                          type: integer
                          nullable: true
                        idOtherEntity:
                          type: integer
                          nullable: true
                        profileLink:
                          type: string
                          nullable: true
                        name:
                          type: string
                          nullable: false
                        number:
                          type: string
                          nullable: true
                  relationships:
                    type: array
                    items:
                      type: object
                      additionalProperties: false
                      required:
                        - sourceNode
                        - targetNode
                        - type
                      properties:
                        sourceNode:
                          type: integer
                          nullable: false
                        targetNode:
                          type: integer
                          nullable: false
                        type:
                          type: string
                          nullable: false
              example:
                nodes:
                  - entityType: person
                    idNode: 123
                    idPerson: 123
                    profileLink: https://platform.mnai.tech/person/123/summary
                    name: John Doe
                  - entityType: company
                    idNode: 456
                    idCompany: 456
                    profileLink: https://platform.mnai.tech/company/456/summary
                    name: ABC Holdings Ltd
                    number: '12345678'
                  - entityType: other
                    idNode: 789
                    name: ABC Holdings Inc
                relationships:
                  - sourceNode: 456
                    targetNode: 123
                    type: officer
                  - sourceNode: 456
                    targetNode: 123
                    type: shareholder
                  - sourceNode: 456
                    targetNode: 789
                    type: psc
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /company/{idCompany}/trading-addresses:
    get:
      summary: Company trading addresses
      description: |
        Retrieve trading addresses of a company by `idCompany`.

        Results are ordered by `address line 1`.
      parameters:
        - name: idCompany
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: ok
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  additionalProperties: false
                  properties:
                    line1:
                      type: string
                      nullable: true
                    line2:
                      type: string
                      nullable: true
                    line3:
                      type: string
                      nullable: true
                    line4:
                      type: string
                      nullable: true
                    town:
                      type: string
                      nullable: true
                    postcode:
                      type: string
                      nullable: true
              example:
                - line1: 789 Officer St
                  line2: null
                  line3: null
                  line4: null
                  town: London
                  postcode: W1B 2BB
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /company/{idCompany}/officers:
    get:
      summary: Company officers
      description: |
        Retrieve officers of a company by `idCompany`.

        Results are ordered by `appointedDate` DESC.
      parameters:
        - name: idCompany
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: ok
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  additionalProperties: false
                  required:
                    - entityType
                    - name
                  properties:
                    entityType:
                      type: string
                      nullable: false
                    profileLink:
                      type: string
                      nullable: true
                    idLinkedUkCompany:
                      type: integer
                      nullable: true
                    idPerson:
                      type: integer
                      nullable: true
                    idOtherEntity:
                      type: integer
                      nullable: true
                    name:
                      type: string
                      nullable: false
                    birthDate:
                      type: string
                      pattern: ^\d{4}-\d{2}$
                      nullable: true
                    role:
                      type: string
                      nullable: false
                    appointedDate:
                      type: string
                      format: date
                      pattern: ^\d{4}-\d{2}-\d{2}$
                      nullable: false
                    resignedDate:
                      type: string
                      format: date
                      pattern: ^\d{4}-\d{2}-\d{2}$
                      nullable: true
                    address:
                      type: object
                      additionalProperties: false
                      properties:
                        line1:
                          type: string
                          nullable: true
                        line2:
                          type: string
                          nullable: true
                        line3:
                          type: string
                          nullable: true
                        line4:
                          type: string
                          nullable: true
                        town:
                          type: string
                          nullable: true
                        postcode:
                          type: string
                          nullable: true
              example:
                - entityType: Person
                  idPerson: 456
                  profileLink: https://platform.mnai.tech/person/456/summary
                  name: Jane Smith
                  birthDate: 1970-01
                  role: Director
                  appointedDate: '2010-05-20'
                  resignedDate: null
                  address:
                    line1: 789 Officer St
                    line2: null
                    line3: null
                    line4: null
                    town: London
                    postcode: W1B 2BB
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /company/{idCompany}/shareholders:
    get:
      summary: Company shareholders
      description: |
        Retrieve shareholders of a company by `idCompany`.

        Results are ordered by `sharesSince` DESC.
      parameters:
        - name: idCompany
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: ok
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  additionalProperties: false
                  required:
                    - entityType
                    - name
                    - shares
                    - sharesSince
                    - sharesUntil
                    - percentage
                  properties:
                    entityType:
                      type: string
                      nullable: false
                    profileLink:
                      type: string
                      nullable: true
                    idLinkedUkCompany:
                      type: integer
                      nullable: true
                    idPerson:
                      type: integer
                      nullable: true
                    idOtherEntity:
                      type: integer
                      nullable: true
                    name:
                      type: string
                      nullable: false
                    shares:
                      type: integer
                      nullable: false
                    sharesSince:
                      type: string
                      format: date
                      pattern: ^\d{4}-\d{2}-\d{2}$
                      nullable: true
                    sharesUntil:
                      type: string
                      format: date
                      pattern: ^\d{4}-\d{2}-\d{2}$
                      nullable: true
                    percentage:
                      type: number
                      format: float
                      minimum: 0
                      maximum: 100
                      example: 25.5
                      nullable: false
              example:
                - entityType: UK Company
                  profileLink: https://platform.mnai.tech/company/456/summary
                  idPerson: null
                  idLinkedUkCompany: 456
                  idOtherEntity: null
                  name: XYZ Holdings Ltd
                  shares: 100
                  sharesSince: '2015-06-30'
                  sharesUntil: null
                  percentage: 12.34
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /company/{idCompany}/shareholdings:
    get:
      summary: Company shareholdings
      description: |
        Retrieve shareholdings of a company by `idCompany`.

        Results are ordered by `incorporatedDate` DESC.
      parameters:
        - name: idCompany
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: ok
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  additionalProperties: false
                  required:
                    - idLinkedUkCompany
                    - profileLink
                    - companyName
                    - companyNumber
                    - incorporatedDate
                    - companyStatus
                    - registerStatus
                    - shares
                    - percentage
                  properties:
                    idLinkedUkCompany:
                      type: integer
                      nullable: false
                    profileLink:
                      type: string
                      nullable: false
                    companyName:
                      type: string
                      nullable: false
                    companyNumber:
                      type: string
                      nullable: false
                    incorporatedDate:
                      type: string
                      format: date
                      pattern: ^\d{4}-\d{2}-\d{2}$
                      nullable: true
                    companyStatus:
                      type: string
                      nullable: false
                    registerStatus:
                      type: string
                      nullable: false
                    shares:
                      type: integer
                      nullable: false
                    sharesSince:
                      type: string
                      format: date
                      pattern: ^\d{4}-\d{2}-\d{2}$
                      nullable: true
                    sharesUntil:
                      type: string
                      format: date
                      pattern: ^\d{4}-\d{2}-\d{2}$
                      nullable: true
                    percentage:
                      type: number
                      format: float
                      minimum: 0
                      maximum: 100
                      multipleOf: 0.01
                      example: 25.5
                      nullable: false
              example:
                - idLinkedUkCompany: 456
                  profileLink: https://platform.mnai.tech/company/456/summary
                  companyName: XYZ Holdings Ltd
                  companyNumber: '12345678'
                  incorporatedDate: '2015-06-30'
                  companyStatus: Active
                  registerStatus: Registered
                  shares: 100
                  sharesSince: '2015-06-30'
                  sharesUntil: null
                  percentage: 12.34
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /company/{idCompany}/charges:
    get:
      summary: Company charges
      description: |
        Retrieve charges of a company by `idCompany`.

        Results are ordered by `createdDate` DESC.
      parameters:
        - name: idCompany
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: ok
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  additionalProperties: false
                  required:
                    - idCharge
                    - chargeCode
                    - description
                    - chargeStatus
                    - createdDate
                  properties:
                    idCharge:
                      type: integer
                      nullable: false
                    chargeCode:
                      type: string
                      nullable: true
                    description:
                      type: string
                      nullable: true
                    chargeStatus:
                      type: string
                      nullable: false
                    createdDate:
                      type: string
                      format: date
                      pattern: ^\d{4}-\d{2}-\d{2}$
                      nullable: true
                    satisfiedDate:
                      type: string
                      format: date
                      pattern: ^\d{4}-\d{2}-\d{2}$
                      nullable: true
                    chargeHolder:
                      type: array
                      items:
                        type: string
                        nullable: false
              example:
                - idCharge: 987
                  chargeCode: ABC123
                  description: Charge on property
                  chargeStatus: Satisfied
                  createdDate: '2010-05-20'
                  satisfiedDate: null
                  chargeHolder:
                    - XYZ Bank
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /company/{idCompany}/judgments:
    get:
      summary: Company judgments
      description: |
        Retrieve judgments of a company by `idCompany`.

        Results are ordered by `judgmentDate` DESC.
      parameters:
        - name: idCompany
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: ok
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  additionalProperties: false
                  required:
                    - idJudgment
                    - caseNumber
                    - categoryCode
                    - categoryName
                    - judgmentDate
                    - amount
                    - courtName
                    - judgmentStatus
                  properties:
                    idJudgment:
                      type: string
                      nullable: false
                    caseNumber:
                      type: string
                      nullable: false
                    categoryCode:
                      type: string
                      nullable: false
                    categoryName:
                      type: string
                      nullable: false
                    judgmentDate:
                      type: string
                      format: date
                      pattern: ^\d{4}-\d{2}-\d{2}$
                      nullable: false
                    amount:
                      type: number
                      format: float
                      nullable: false
                    courtName:
                      type: string
                      nullable: false
                    judgmentStatus:
                      type: string
                      nullable: false
                    satisfiedDate:
                      type: string
                      format: date
                      pattern: ^\d{4}-\d{2}-\d{2}$
                      nullable: true
              example:
                - idJudgment: 3cc1cb31-fcac-4a67-998b-ec675084994e
                  caseNumber: G25YX983
                  categoryCode: CCJ
                  categoryName: County Court Judgements
                  judgmentDate: '2010-05-20'
                  amount: 1234.99
                  courtName: London County Court
                  judgmentStatus: Satisfied
                  satisfiedDate: '2015-06-30'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
