openapi: 3.1.0
info:
  title: DNV Class Status Certificates Vessels API
  description: DNV's Class Status API provides programmatic access to vessel classification data. Authentication uses OAuth 2.0 with Azure AD B2C as the identity provider. Access tokens are obtained from the Microsoft identity platform and are valid for approximately 20 minutes. Access requires a separate API contract with DNV. The API supports retry logic using exponential backoff for resilience.
  version: 1.0.0
  contact:
    name: DNV Support
    url: https://help-center.veracity.com/en/
  license:
    name: DNV Terms
    url: https://www.dnv.com/terms/
servers:
- url: https://maritime.dnv.com/api/cs-iacs-customer
  description: DNV Class Status API Production
security:
- oauth2: []
tags:
- name: Vessels
  description: Vessel classification status and information
paths:
  /vessels:
    get:
      operationId: searchVessels
      summary: Search vessels by classification criteria
      description: Searches for vessels in DNV's classification register. Supports filtering by vessel name, IMO number, flag state, ship type, and classification status. Returns vessel summaries including class notation and current status.
      tags:
      - Vessels
      parameters:
      - name: imoNumber
        in: query
        description: IMO vessel identification number (7 digits)
        schema:
          type: string
          pattern: ^[0-9]{7}$
      - name: vesselName
        in: query
        description: Vessel name (partial match supported)
        schema:
          type: string
      - name: flagState
        in: query
        description: ISO 3166-1 alpha-2 country code for flag state
        schema:
          type: string
          pattern: ^[A-Z]{2}$
      - name: shipType
        in: query
        description: DNV ship type classification code
        schema:
          type: string
      - name: classStatus
        in: query
        description: Current class status filter
        schema:
          type: string
          enum:
          - CLASSED
          - SUSPENDED
          - WITHDRAWN
          - DELETED
      - name: limit
        in: query
        schema:
          type: integer
          default: 50
          maximum: 200
      - name: offset
        in: query
        schema:
          type: integer
          default: 0
      responses:
        '200':
          description: List of vessels matching search criteria
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VesselList'
            application/xml:
              schema:
                $ref: '#/components/schemas/VesselList'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /vessels/{imoNumber}:
    get:
      operationId: getVessel
      summary: Get vessel classification details
      description: Returns detailed classification information for a specific vessel identified by IMO number, including class notation, survey status, and certificates.
      tags:
      - Vessels
      parameters:
      - name: imoNumber
        in: path
        required: true
        description: IMO vessel identification number (7 digits)
        schema:
          type: string
          pattern: ^[0-9]{7}$
      - name: Accept
        in: header
        description: Response format
        schema:
          type: string
          default: application/json
          enum:
          - application/json
          - application/xml
      responses:
        '200':
          description: Vessel classification details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Vessel'
            application/xml:
              schema:
                $ref: '#/components/schemas/Vessel'
        '404':
          $ref: '#/components/responses/NotFound'
  /fleets:
    get:
      operationId: getFleetStatus
      summary: Get fleet classification status
      description: Returns classification status for a fleet of vessels. Useful for fleet managers to monitor the overall compliance status of their vessels.
      tags:
      - Vessels
      parameters:
      - name: imoNumbers
        in: query
        description: Comma-separated list of IMO numbers (max 100)
        schema:
          type: string
      - name: includeExpiredCerts
        in: query
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: Fleet status summary
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FleetStatus'
components:
  responses:
    Forbidden:
      description: No API contract with DNV for this resource
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Authentication token missing or expired
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Vessel not found in DNV register
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    FleetStatus:
      type: object
      properties:
        requestedCount:
          type: integer
        foundCount:
          type: integer
        vessels:
          type: array
          items:
            type: object
            properties:
              imoNumber:
                type: string
              vesselName:
                type: string
              classStatus:
                type: string
              nextSurveyDue:
                type: string
                format: date
              certificatesExpiringSoon:
                type: integer
    Vessel:
      allOf:
      - $ref: '#/components/schemas/VesselSummary'
      - type: object
        properties:
          vesselOwner:
            type: string
          technicalManager:
            type: string
          buildYear:
            type: integer
          grossTonnage:
            type: number
          deadweightTonnage:
            type: number
          length:
            type: number
            description: Length overall in meters
          beam:
            type: number
            description: Breadth in meters
          draught:
            type: number
            description: Maximum draught in meters
          mainEngineType:
            type: string
          mainEnginePower:
            type: number
            description: Main engine output in kW
          hullMaterial:
            type: string
            enum:
            - STEEL
            - ALUMINUM
            - GRP
            - WOOD
          surveys:
            $ref: '#/components/schemas/SurveySummary'
          nextSurveyDue:
            type: string
            format: date
    SurveySummary:
      type: object
      properties:
        lastAnnualSurvey:
          type: string
          format: date
        nextAnnualSurveyDue:
          type: string
          format: date
        lastSpecialSurvey:
          type: string
          format: date
        nextSpecialSurveyDue:
          type: string
          format: date
    VesselSummary:
      type: object
      properties:
        imoNumber:
          type: string
          description: IMO vessel identification number
        vesselName:
          type: string
        flagState:
          type: string
          description: ISO 3166-1 alpha-2 flag state code
        shipType:
          type: string
        classStatus:
          type: string
          enum:
          - CLASSED
          - SUSPENDED
          - WITHDRAWN
          - DELETED
        classNotation:
          type: string
          description: Full DNV class notation string
    Error:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
        requestId:
          type: string
    VesselList:
      type: object
      properties:
        total:
          type: integer
        offset:
          type: integer
        vessels:
          type: array
          items:
            $ref: '#/components/schemas/VesselSummary'
  securitySchemes:
    oauth2:
      type: oauth2
      description: OAuth 2.0 via Azure AD B2C. Tokens obtained from https://login.microsoftonline.com/dnvglb2cprod.onmicrosoft.com/oauth2/token using client credentials grant with resource ID c916a223-f3d4-4d43-b709-cfcd77ff4a05.
      flows:
        clientCredentials:
          tokenUrl: https://login.microsoftonline.com/dnvglb2cprod.onmicrosoft.com/oauth2/token
          scopes:
            class_status:read: Read vessel classification status