hm-eligibility-v1.yml

openapi: 3.0.3
info:
  title: Eligibility API
  description: |-
    This API allows lookups to see if a vehicle is eligible for telematics data.
    
    
    In order to use the API endpoints you will need to retrieve an access token using the [OAuth API](/api-references/code-references/oauth2/reference/v1/) with `client_credentials` grant
    
    * Sandbox server: `https://sandbox.api.high-mobility.com`
    * Production server: `https://api.high-mobility.com`
    
    Note that in production, the brands of the VINs that are being checked have to first be activated for your application before you can do lookups.
  contact:
    email: support@high-mobility.com
  version: 1.0.0
externalDocs:
  description: High Mobility's Developer Console
  url: https://console.high-mobility.com
servers:
  - url: https://api.high-mobility.com
  - url: https://sandbox.api.high-mobility.com  

paths:
  /v1/eligibility:
    post:
      deprecated: false
      security:
        - EligibilityAuth:
          - vehicle:eligibility-check
      tags:
        - Eligibility
      summary: Check vehicle eligibility
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
          description: Vehicle eligibility requested successfully
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EligibilityUnauthorizedErrors'
          description: When an invalid ServiceAccountToken is used.
        '422':
          content:
            application/json:
              schema:        
                $ref: '#/components/schemas/GeneralErrors'
          description: Errors such as invalid VIN and brand call failed
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Request'      
      description: >-
        Retrieves the eligibility status for a specific VIN. This can be used to
        find out if the vehicle has the necessary connectivity to transmit data.


components:
  schemas:
    SuccessResponse:
      type: object
      title: SuccessResponse
      properties:
        vin:
          type: string
        eligible:
          type: boolean
        data_delivery:
          type: array
          items:
            type: string
            enum:
              - pull
              - push
        connectivity_status:
          type: string
          enum:
            - activated
            - deactivated
            - unknown
        primary_user_assigned:
          type: boolean
      required:
        - vin
        - eligible
        - data_delivery
      example:
        vin: EXVETESTVIN000001
        eligible: true
        data_delivery:
          - pull
          - push
      description: Response of eligibility check
    Request:
      type: object
      properties:
        vin:
          type: string
          description: Vehicle vin.
        brand:
          type: string
          enum:
            - mercedes-benz
            - ford
            - bmw
            - mini
            - citroen
            - peugeot
            - opel
            - vauxhall
            - ds
            - jeep
            - fiat
            - alfaromeo
            - renault
            - toyota
            - lexus
            - sandbox
      required:
        - vin
        - brand
    EligibilityUnauthorizedErrors:
      type: object
      title: Errors
      properties:
        errors:
          description: List of errors
          type: array
          items:
            $ref: '#/components/schemas/Error'
          example:
            - detail: >
                Missing or invalid authorization header. The token must be
                obtained through the service account API and sent as a header with
                the format "Authorization: Bearer <token>"
              source: Authorization
              title: Not authorized
    GeneralErrors:
      type: object
      title: Errors
      properties:
        errors:
          description: List of errors
          type: array
          items:
            $ref: '#/components/schemas/Error'
    Error:
      type: object
      title: Error
      required:
        - title
      properties:
        title:
          type: string
          description: Error title
        source:
          type: string
          description: Field that has problem
        detail:
          type: string
          description: Error detail
      description: Error details

  securitySchemes:
    EligibilityAuth:
      flows:
        clientCredentials:
          scopes:
            vehicle:eligibility-check: eligibility check
          tokenUrl: https://api.sandbox.high-mobility.com/v1/access_token
      type: oauth2