openapi: 3.1.0
info:
  title: MeshVI API
  description: >-
    API documentation for MeshVI services. These endpoints require API
    authorization ([APIAuthorize]) via Bearer token. Includes Acord certificate
    verification and retrieval, client, driver, policy, and vehicle operations
    for real-time insurance verification and fleet management.
  version: 1.0.0
servers:
  - url: https://verified.meshvi.com
    description: Production
paths:
  /v1/certificates/clients:
    get:
      tags:
        - Certificates
      summary: Get client certificate
      description: >-
        Retrieves the Acord certificate for a client. Provide either client id
        or DOT number (exactly one).
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: query
          description: Client ID.
          schema:
            type:
              - integer
              - 'null'
        - name: dot
          in: query
          description: DOT number (digits only).
          schema:
            type:
              - string
              - 'null'
      responses:
        '200':
          description: Certificate data returned successfully.
          content:
            application/json:
              schema:
                type: object
                description: Certificate response object.
        '400':
          description: Bad Request (e.g. missing or invalid parameters).
        '401':
          description: Unauthorized.
        '500':
          description: Internal server error.
  /v1/coverages/clients:
    get:
      tags:
        - Certificates
      summary: Verify COI for clients
      description: >-
        Verifies active certificates of insurance across DOT numbers. Provide
        exactly one of: dots (array), dot (single), or id (client ID).
      security:
        - BearerAuth: []
      parameters:
        - name: dots
          in: query
          description: List of DOT numbers to verify.
          schema:
            type:
              - array
              - 'null'
            items:
              type: string
        - name: dot
          in: query
          description: Single DOT number (digits only).
          schema:
            type:
              - string
              - 'null'
        - name: id
          in: query
          description: Client ID.
          schema:
            type:
              - integer
              - 'null'
      responses:
        '200':
          description: Successful verification.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CertificateVerificationResponse'
        '400':
          description: Bad Request (e.g. missing or invalid parameters).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized.
  /v1/coverages/vehicles:
    get:
      tags:
        - Certificates
      summary: Verify vehicle COI
      description: >-
        Verifies certificate of insurance for a vehicle. Provide either vin or
        licensePlate (exactly one).
      security:
        - BearerAuth: []
      parameters:
        - name: vin
          in: query
          description: VIN (17 characters).
          schema:
            type:
              - string
              - 'null'
            minLength: 17
            maxLength: 17
        - name: licensePlate
          in: query
          description: License plate number.
          schema:
            type:
              - string
              - 'null'
      responses:
        '200':
          description: Successful verification.
          content:
            application/json:
              schema:
                type: object
        '400':
          description: Bad Request (provide either vin or licensePlate, not both).
        '401':
          description: Unauthorized.
  /v1/certificates/vehicles:
    get:
      tags:
        - Certificates
        - Vehicles
      summary: Get vehicle certificate
      description: >-
        Retrieves the Acord certificate for a vehicle. Provide exactly one of:
        id, vin, or licensePlate. clientId may be used in some contexts.
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: query
          description: Vehicle ID.
          schema:
            type:
              - integer
              - 'null'
        - name: vin
          in: query
          description: VIN (17 characters).
          schema:
            type:
              - string
              - 'null'
            minLength: 17
            maxLength: 17
        - name: licensePlate
          in: query
          description: License plate number.
          schema:
            type:
              - string
              - 'null'
        - name: clientId
          in: query
          description: Client ID (optional context).
          schema:
            type:
              - integer
              - 'null'
      responses:
        '200':
          description: Certificate data returned successfully.
          content:
            application/json:
              schema:
                type: object
        '400':
          description: Bad Request.
        '401':
          description: Unauthorized.
        '500':
          description: Internal server error.
  /v1/clients:
    get:
      tags:
        - Clients
      summary: Search clients
      description: >-
        Paginated search of clients with filtering and sorting. Supports page,
        limit, sort, and filters (name, dot, agencyId, producerId,
        parentClientId, deleted, clientTypeId, acordEnabled).
      security:
        - BearerAuth: []
      parameters:
        - name: page
          in: query
          description: Page number (1-based).
          schema:
            type: integer
            minimum: 1
            default: 1
        - name: limit
          in: query
          description: Items per page (1-1000).
          schema:
            type: integer
            minimum: 1
            maximum: 1000
            default: 100
        - name: sort
          in: query
          description: Sort field (e.g. -clientName for descending).
          schema:
            type: string
        - name: name
          in: query
          description: Filter by client name (partial match).
          schema:
            type: string
        - name: dot
          in: query
          description: Filter by DOT number.
          schema:
            type: string
        - name: agencyId
          in: query
          description: Filter by agency ID.
          schema:
            type:
              - integer
              - 'null'
        - name: producerId
          in: query
          description: Filter by producer ID.
          schema:
            type:
              - integer
              - 'null'
        - name: parentClientId
          in: query
          description: Filter by parent client ID.
          schema:
            type:
              - integer
              - 'null'
        - name: deleted
          in: query
          description: Filter by deleted status.
          schema:
            type:
              - boolean
              - 'null'
        - name: clientTypeId
          in: query
          description: Filter by client type ID.
          schema:
            type:
              - integer
              - 'null'
        - name: acordEnabled
          in: query
          description: Filter by ACORD enabled.
          schema:
            type:
              - boolean
              - 'null'
      responses:
        '200':
          description: Paginated list of clients.
        '400':
          description: Invalid query parameters.
        '401':
          description: Unauthorized.
    post:
      tags:
        - Clients
      summary: Create client
      description: >-
        Creates a new client. Required: clientName, agencyId. Optional:
        producerId and other client fields.
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - clientName
                - agencyId
              properties:
                clientName:
                  type: string
                  example: Acme Trucking
                agencyId:
                  type: integer
                  example: 1
                producerId:
                  type:
                    - integer
                    - 'null'
                  example: 1
      responses:
        '201':
          description: Client created successfully.
        '400':
          description: Invalid request data.
        '401':
          description: Unauthorized.
  /v1/clients/{id}:
    get:
      tags:
        - Clients
      summary: Get client detail
      description: Retrieves client details by ID.
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          description: Client ID.
          schema:
            type: integer
      responses:
        '200':
          description: Client details.
        '400':
          description: Invalid id.
        '401':
          description: Unauthorized.
        '404':
          description: Client not found.
    put:
      tags:
        - Clients
      summary: Update client
      description: Updates an existing client. Only provided fields are updated.
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          description: Client identifier.
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                clientName:
                  type: string
                  example: Acme Trucking
                agencyId:
                  type:
                    - integer
                    - 'null'
                  example: 1
                producerId:
                  type:
                    - integer
                    - 'null'
                  example: 1
      responses:
        '200':
          description: Client updated successfully.
        '400':
          description: Invalid request data.
        '401':
          description: Unauthorized.
        '404':
          description: Client not found.
  /v1/drivers/search:
    post:
      tags:
        - Drivers
      summary: Search drivers
      description: Returns a paginated list of drivers based on filter and paging request.
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                filter:
                  type: object
                  description: Driver filter criteria.
                pageIndex:
                  type: integer
                  example: 1
                pageSize:
                  type: integer
                  example: 20
                sortBy:
                  type: string
                  example: name
                sortOrder:
                  type: string
                  example: asc
      responses:
        '200':
          description: Paginated driver list.
        '400':
          description: Bad Request.
        '401':
          description: Unauthorized.
        '500':
          description: Internal server error.
  /v1/policies:
    get:
      tags:
        - Policies
      summary: Search policies
      description: >-
        Paginated search of policies. Query params: page, limit, sort, q,
        policy, clientId, deleted, status, coverageType.
      security:
        - BearerAuth: []
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            minimum: 1
            default: 1
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 1000
            default: 100
        - name: sort
          in: query
          schema:
            type: string
        - name: q
          in: query
          description: Search text.
          schema:
            type: string
        - name: policy
          in: query
          description: Policy number filter.
          schema:
            type: string
        - name: clientId
          in: query
          schema:
            type:
              - integer
              - 'null'
        - name: deleted
          in: query
          schema:
            type:
              - boolean
              - 'null'
        - name: status
          in: query
          description: all, active, cancelled, future, expired.
          schema:
            type: string
        - name: coverageType
          in: query
          description: PD, NT, OA, PA, CG, AL, GL, WC, TI, DD, VD.
          schema:
            type: string
      responses:
        '200':
          description: Paginated list of policies.
        '400':
          description: Invalid query parameters.
        '401':
          description: Unauthorized.
    post:
      tags:
        - Policies
      summary: Create policy
      description: >-
        Creates a new policy. Required: clientId, coverageType, effectiveDate,
        expirationDate.
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - clientId
                - coverageType
                - effectiveDate
                - expirationDate
              properties:
                clientId:
                  type: integer
                  example: 1
                coverageType:
                  type: string
                  example: AL
                effectiveDate:
                  type: string
                  format: date-time
                  example: '2024-01-01T00:00:00Z'
                expirationDate:
                  type: string
                  format: date-time
                  example: '2025-01-01T00:00:00Z'
      responses:
        '201':
          description: Policy created successfully.
        '400':
          description: Invalid request data.
        '401':
          description: Unauthorized.
  /v1/policies/{id}:
    get:
      tags:
        - Policies
      summary: Get policy detail
      description: Retrieves policy details by ID.
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          description: Policy identifier.
          schema:
            type: integer
      responses:
        '200':
          description: Policy details.
        '400':
          description: Bad Request.
        '401':
          description: Unauthorized.
        '404':
          description: Policy not found.
        '500':
          description: Internal server error.
  /v1/policies/search:
    post:
      tags:
        - Policies
      summary: Get policy list
      description: >-
        Returns a paginated list of policies based on filter and paging request
        (body).
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                filter:
                  type: object
                pageIndex:
                  type: integer
                  example: 1
                pageSize:
                  type: integer
                  example: 20
                sortBy:
                  type: string
                  example: effectiveDate
                sortOrder:
                  type: string
                  example: desc
      responses:
        '200':
          description: Paginated policy list.
        '400':
          description: Bad Request.
        '401':
          description: Unauthorized.
        '500':
          description: Internal server error.
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    CertificateVerificationResponse:
      type: object
      properties:
        results:
          type: array
          items:
            oneOf:
              - $ref: '#/components/schemas/CertificateVerificationResult'
              - $ref: '#/components/schemas/DotNotFoundResponse'
    CertificateVerificationResult:
      type: object
      properties:
        dotNumber:
          type: string
          description: Department of Transportation (DOT) number.
          example: '123456'
        clients:
          type: array
          items:
            $ref: '#/components/schemas/ClientCOIInfo'
    ClientCOIInfo:
      type: object
      properties:
        clientName:
          type: string
          example: Example Trucking Co
        clientId:
          type: integer
          example: 1001
        certificateExists:
          type: boolean
          example: true
        policies:
          type: array
          items:
            $ref: '#/components/schemas/PolicyCOIInfo'
    PolicyCOIInfo:
      type: object
      properties:
        policyNumber:
          type: string
          example: POL-998877
        coverageType:
          type: string
          example: Auto Liability
        coverageLimit:
          type:
            - integer
            - 'null'
          example: 1000000
        effectiveDate:
          type: string
          format: date-time
          example: '2024-01-01T00:00:00Z'
        expirationDate:
          type: string
          format: date-time
          example: '2025-01-01T00:00:00Z'
        unitCoverages:
          $ref: '#/components/schemas/UnitCoverages'
    UnitCoverages:
      type: object
      properties:
        anyAuto:
          type:
            - boolean
            - 'null'
          example: true
        ownedAutoOnly:
          type:
            - boolean
            - 'null'
          example: false
        hiredAutosOnly:
          type:
            - boolean
            - 'null'
          example: false
        nonOwnedAutosOnly:
          type:
            - boolean
            - 'null'
          example: false
        scheduledAutos:
          type:
            - boolean
            - 'null'
          example: true
    DotNotFoundResponse:
      type: object
      properties:
        dotNumber:
          type: string
          example: '999999'
        message:
          type: string
          example: DOT number not found
    ErrorResponse:
      type: object
      properties:
        error:
          oneOf:
            - type: string
              example: Validation failed
            - type: object
              properties:
                ErrorCode:
                  type: integer
                  example: 1001
                ErrorText:
                  type: string
                  example: Process failed
  x-tagGroups:
    - name: Certificates
      tags:
        - Certificates
    - name: Clients
      tags:
        - Clients
    - name: Drivers
      tags:
        - Drivers
    - name: Policies
      tags:
        - Policies
    - name: Vehicles
      tags:
        - Vehicles
tags:
  - name: Certificates
    description: Certificate verification and retrieval (Acord).
  - name: Clients
    description: Client CRUD and search.
  - name: Drivers
    description: Driver search and list.
  - name: Policies
    description: Policy CRUD and search.
  - name: Vehicles
    description: Vehicle certificate operations.
security:
  - BearerAuth: []
