openapi: 3.0.1
info:
  title: ClearVIN Vendor API
  description: >-
    REST API for ClearVIN's VIN decoding and vehicle history data. Clients
    exchange account credentials for a JWT bearer token at /rest/vendor/login,
    then request vehicle data by VIN from /rest/vendor/report. A single report
    endpoint returns VIN decode specifications, NMVTIS title and history data,
    and market valuation depending on the account subscription. Requests must
    originate from an IP address registered with ClearVIN. Documented endpoint
    paths are limited to login and report; additional product surfaces are
    served through the report endpoint.
  termsOfService: https://www.clearvin.com/en/terms-of-service/
  contact:
    name: ClearVIN
    url: https://www.clearvin.com/en/contact/
  version: '1.0'
servers:
  - url: https://www.clearvin.com
    description: ClearVIN production API
paths:
  /rest/vendor/login:
    post:
      operationId: login
      tags:
        - Authentication
      summary: Authenticate and obtain a bearer token.
      description: >-
        Exchanges account email and password for a JWT bearer token that is
        valid for 120 minutes. The request must originate from an IP address
        registered with ClearVIN.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LoginRequest'
      responses:
        '200':
          description: Authentication result with token on success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoginResponse'
  /rest/vendor/report:
    get:
      operationId: getReport
      tags:
        - Report
      summary: Retrieve a vehicle report by VIN.
      description: >-
        Returns a vehicle report for the supplied VIN. Depending on the account
        subscription the report contains VIN decode specifications, NMVTIS title
        and history data, and / or market valuation. By default the response is
        JSON; pass format=html to receive an HTML rendering of the report.
        Requires a valid bearer token from /rest/vendor/login.
      security:
        - bearerAuth: []
      parameters:
        - name: vin
          in: query
          required: true
          description: The 17-character Vehicle Identification Number to look up.
          schema:
            type: string
          example: 5UXFA13544LU21050
        - name: format
          in: query
          required: false
          description: >-
            Response format. Omit for JSON (default) or set to html to receive
            an HTML rendering of the report.
          schema:
            type: string
            enum:
              - html
      responses:
        '200':
          description: Report result for the requested VIN.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReportResponse'
            text/html:
              schema:
                type: string
                description: HTML rendering of the report when format=html.
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        JWT obtained from /rest/vendor/login, sent as
        "Authorization: Bearer {token}". Tokens expire after 120 minutes.
  schemas:
    LoginRequest:
      type: object
      required:
        - email
        - password
      properties:
        email:
          type: string
          format: email
          description: Account email address.
        password:
          type: string
          format: password
          description: Account password.
    LoginResponse:
      type: object
      properties:
        status:
          type: string
          description: Result status, "ok" on success or "error" on failure.
          enum:
            - ok
            - error
        message:
          type: string
          description: Error detail, present when status is "error".
        token:
          type: string
          description: JWT bearer token, present when status is "ok". Valid 120 minutes.
    ReportResponse:
      type: object
      properties:
        status:
          type: string
          description: Result status, "ok" on success or "error" on failure.
          enum:
            - ok
            - error
        message:
          type: string
          description: Error detail, present when status is "error".
        result:
          $ref: '#/components/schemas/ReportResult'
    ReportResult:
      type: object
      properties:
        id:
          type: string
          description: ClearVIN report identifier.
        vin:
          type: string
          description: The VIN the report was generated for.
        report:
          $ref: '#/components/schemas/Report'
    Report:
      type: object
      description: >-
        Vehicle report payload. Field structure varies by subscription and
        data availability; the decoder, history, and valuation sections below
        are representative and require reconciliation against a live account
        response for exact shapes.
      properties:
        decoder:
          type: object
          description: >-
            VIN decode output - up to 150 specification parameters such as year,
            make, model, trim, engine, body, dimensions, standard features, and
            recall data.
          additionalProperties: true
        nmvtis:
          type: object
          description: >-
            NMVTIS title and history data - DMV title records, brand codes,
            junk / salvage / total-loss events, insurance claims, and odometer /
            mileage history.
          additionalProperties: true
        valuation:
          type: object
          description: >-
            Market valuation data - wholesale, retail, and trade-in values
            across condition categories, with mileage adjustments.
          additionalProperties: true