Skip to content

Vinni API Documentation

Automotive document processing and vehicle analysis APIs

Table of Contents

  1. Analyze Docs
  2. Analyze Vehicle
  3. Verification
  4. History

Analyze Docs

Endpoint

POST /analyzeDocs

Description

This endpoint processes vehicle documents and extracts detailed information. It utilizes image processing, computer vision, and AI-powered data extraction to analyze the images and return structured information in JSON format.

Request Format

Headers

  • Content-Type: application/json
  • authorizationToken: <your_api_key>
{
    "Content-Type": "application/json",
    "authorizationToken": "AUTH_TOKEN_HERE"
}

Body

{
  "doc_images": [
    {
      "base64": "data:image/jpeg;base64,..."
    },
    {
      "url": "https://example.com/image.jpg"
    },
    {
      "s3_path": "s3://bucket-name/path/to/image.jpg"
    }
  ],
  "doc": "Vehicle Title Document",
  "uuid": "optional-uuid"
}

Parameters

Parameter Type Required Description
doc_images array Yes An array containing up to 8 images of the vehicle title document. Each image object must include one of the following keys: base64, url, or s3_path.
doc string No A string description of the document type. Default is "vehicle title".
uuid string No A custom UUID for the request. If not provided, a UUID will be generated.

Responses

Success Response

Code: 200 OK

{
  "results": {
    // Extracted information (see detailed schema below)
  },
  "timestamp": "20240716123456",
  "uuid": "550e8400-e29b-41d4-a716-446655440000"
}

Error Responses

Code: 400 Bad Request

{
  "message": "Invalid input or missing required fields"
}

Code: 500 Internal Server Error

{
  "message": "Internal server error: <error_message>"
}

Detailed Field Descriptions

title_details

  • state: String representing the state issuing the title.
  • document_type: String indicating the type of document (e.g., "Title").
  • form_control_number: String representing the form control number on the document.
  • title_document_number: String representing the unique title document number.
  • issued_by: String indicating the issuing authority (e.g., "California DMV").
  • issue_date: String representing the date of issue in "YYYY-MM-DD" format.
  • remarks_legends_brands: String containing any additional remarks or legends on the title.

vehicle_details

  • vehicle_identification_number_vin: String representing the Vehicle Identification Number.
  • year: Integer representing the vehicle's year of manufacture.
  • make: String representing the vehicle's make.
  • model: String representing the vehicle's model.
  • body: String representing the vehicle's body type.
  • style_class: String representing the vehicle's style or class.
  • color: String representing the vehicle's color.
  • sale_type: String indicating whether the vehicle is new or used.
  • odometer_reading: Number representing the current odometer reading.
  • odometer_status: String indicating the status of the odometer reading (e.g., "Actual").
  • mfg_capacity_in_tons: Number representing the manufacturing capacity in tons.
  • weight: Number representing the vehicle's weight.
  • license_plate_number: String representing the vehicle's license plate number.

owner_details

  • owner_name_and_address: String containing the full name and address of the owner.
  • owner_name: String representing the owner's name.
  • street_address: String representing the owner's street address.
  • city: String representing the owner's city.
  • state: String representing the owner's state.
  • zip_code: String representing the owner's ZIP code.
  • co_owner: Boolean indicating whether there is a co-owner on the vehicle.
  • driver_license_1: String representing the owner's driver's license number.
  • driver_license_2: String representing the co-owner's driver's license number (if applicable).
  • mailing_address: String representing the owner's mailing address.
  • owner_signature: Boolean indicating whether the owner's signature is present.
  • purchased_date: String representing the date of purchase in "YYYY-MM-DD" format.

previous_owner_details

  • previous_owner: String representing the name of the previous owner.
  • previous_owner_address: String representing the address of the previous owner.
  • previous_title_number: String representing the previous title number.
  • previous_title_state: String representing the state of the previous title.

lien_details

An array of objects, each containing:

  • lien_date: String representing the date the lien was placed in "YYYY-MM-DD" format.
  • lien_holder: String representing the name of the lien holder.
  • lien_holder_address: String representing the address of the lien holder.
  • lien_released_date: String representing the date the lien was released in "YYYY-MM-DD" format.
  • lien_released_agent: String representing the name of the agent who released the lien.
  • lien_released_signature_stamp: Boolean indicating whether a signature or stamp for lien release is present.

parsing_errors

An array of objects, each containing:

  • field_name: String representing the name of the field where an error occurred.
  • error_message: String describing the error.

Additional Information

  • UUID Usage: Each request is assigned a UUID for tracking and consistency in storage. If a custom UUID is not provided in the request, the server will generate one.
  • Error Handling: The API will return appropriate error messages for invalid inputs or server errors.

Limitations

  • Supported image formats: JPEG, PNG
  • Maximum file size: 10 MB per image

Analyze Vehicle

Endpoint

POST /analyzeVehicle

Description

This endpoint processes a set of vehicle images (between 2 and 8) and an optional odometer image. The API extracts detailed information about the vehicle, verifies the extracted data against customer-reported information, and performs damage assessment. It uses image processing, computer vision, and AI-powered analysis to provide a comprehensive report on the vehicle's condition and details.

Request Format

Headers

  • Content-Type: application/json
  • authorizationToken: <your_api_key>
{
    "Content-Type": "application/json",
    "authorizationToken": "AUTH_TOKEN_HERE"
}

Body

{
  "vehicle_images": [
    {
      "base64": "data:image/jpeg;base64,..."
    },
    {
      "url": "https://example.com/image.jpg"
    },
    {
      "s3_path": "s3://bucket-name/path/to/image.jpg"
    }
  ],
  "odometer_image": {
    "base64": "data:image/jpeg;base64,..."
  },
  "plate": "ABC123",
  "state": "CA",
  "make": "Toyota",
  "model": "Corolla",
  "year": "2020",
  "odometer": "50000",
  "uuid": "optional-uuid"
}

Parameters

Parameter Type Required Description
vehicle_images array Yes An array containing between 2 and 8 images of the vehicle. Each image object must include one of the following keys: base64, url, or s3_path.
odometer_image object No An object representing the odometer image. It must include one of the following keys: base64, url, or s3_path.
plate string No The customer-reported license plate number.
state string No The customer-reported state of the vehicle registration.
make string No The customer-reported make of the vehicle.
model string No The customer-reported model of the vehicle.
year string No The customer-reported year of the vehicle.
odometer string No The customer-reported odometer reading of the vehicle.
uuid string No A custom UUID for the request. If not provided, a UUID will be generated.

Responses

Success Response

Code: 200 OK

{
  "results": {
    "vehicle_photos": {
      // Vehicle photo analysis results
    },
    "vehicle_details": {
      // Extracted vehicle details
    },
    "damage_assessment": {
      // Damage assessment results
    },
    "verification": {
      // Verification results
    },
    "parsing_errors": []
  },
  "timestamp": "20240716123456",
  "uuid": "550e8400-e29b-41d4-a716-446655440000"
}

Error Responses

Code: 400 Bad Request

{
  "message": "Please provide between 2 and 8 vehicle images."
}

Code: 500 Internal Server Error

{
  "message": "Internal server error: <error_message>"
}

Detailed Field Descriptions

vehicle_photos

  • are_photos_of_vehicle: Boolean indicating whether the provided images are indeed of a vehicle.
  • original_photos: Boolean indicating whether the images are original photos or pictures of another screen.
  • original_photos_conf: Integer (0-100) representing the confidence score for the assessment of photo originality.
  • original_photos_description: String providing reasoning for categorizing the photos as original or not.
  • same_vehicle: Boolean indicating whether all vehicle images depict the same vehicle.

vehicle_details

  • license_plate_number: String representing the license plate number visible in the vehicle images.
  • license_plate_state: String representing the state of the license plate (two-letter abbreviation).
  • registration_month: String representing the month of the registration sticker on the license plate (two-digit format: MM).
  • registration_year: String representing the year of the registration sticker on the license plate (four-digit format: YYYY).
  • make: String representing the vehicle make.
  • model: String representing the vehicle model.
  • date_range: String representing the year range of the vehicle model.
  • type: String representing the type of vehicle (e.g., car, truck, SUV, motorcycle).
  • color: String representing the vehicle color.
  • odometer: Integer representing the numerical value from the odometer with no units or decimals.

damage_assessment

  • damage_present: Boolean indicating whether there is any damage to the vehicle.
  • damage_description: String describing the vehicle damage and its location.
  • damage_confidence: Integer (0-100) representing the confidence score for the detected damage.
  • damage_severity: Integer (0-10) representing the severity of the damage, where 0 is no damage and 10 is the worst.

verification

  • odometer_verified: Boolean indicating whether the extracted odometer value matches the customer-reported odometer value.
  • year_verified: Boolean indicating whether the extracted vehicle year is within the date range and matches the customer-reported vehicle year.
  • make_verified: Boolean indicating whether the extracted make matches the customer-reported vehicle make.
  • model_verified: Boolean indicating whether the extracted model matches the customer-reported vehicle model.
  • license_plate_verified: Boolean indicating whether the extracted license plate number matches the customer-reported license plate number and state.

parsing_errors

An array of objects, each containing:

  • field_name: String representing the name of the field where an error occurred.
  • error_message: String describing the error.

Additional Information

  • UUID Usage: Each request is assigned a UUID for tracking and consistency in storage. If a custom UUID is not provided in the request, the server will generate one.
  • Error Handling: The API will return appropriate error messages for invalid inputs or server errors.

Limitations

  • A minimum of 2 and a maximum of 8 vehicle images can be processed in a single request.
  • Supported image formats: JPEG, PNG
  • Maximum file size: 10 MB per image

Verification

Endpoint

POST /verification

Description

This API provides verification of the VIN, owner, and issue date on the vehicle title. The user provides seed values for the owner's name, VIN, and title issue date. The API verifies this information is present and accurate on the title. Additional values are returned as best effort based on the ability to reconstruct key-value pairs from the title form.

Request Format

Headers

  • Content-Type: application/json
  • authorizationToken: <your_api_key>
{
    "Content-Type": "application/json",
    "authorizationToken": "AUTH_TOKEN_HERE"
}

Body

{
  "path": "string",
  "vin": "string",
  "title date": "string",
  "owner": "string",
  "watch": "string"
}

Parameters

Parameter Type Required Description
path string Yes The path to the title image in JPEG, PNG, PDF, or TIFF format. This can be an S3 path, HTTP(S) URL, or a base64 encoded byte string.
vin string Yes The vehicle VIN. If the full VIN is not known, enter as many alphanumeric characters of the VIN as possible.
title date string Yes The issue date of the most recent title. The API will validate that the title image has a title issue date within 5 days of this provided title date.
owner string Yes The owner name.
watch string No A string of terms separated by commas to alert on. The API searches for exact matches (not case sensitive) of these terms in the document.

Responses

Success Response

Code: 200 OK

{
  "code": 200,
  "message": "Success",
  "responseData": {
    "vin": {
      // VIN verification details
    },
    "title date": {
      // Title date verification details
    },
    "owner": {
      // Owner verification details
    },
    // Additional extracted information
  }
}

Error Responses

Code: 403 Forbidden

{
  "detail": "You do not have permission to perform this action."
}

Detailed Field Descriptions

  • Key: The key found on the document (e.g., "WEIGHT").
  • Value: The value of the field on the document (e.g., "3700").
  • PairConfidence: The confidence value that indicates if the key and value are a pair.
  • KeyConfidence: The confidence value of extraction of the key.
  • ValueConfidence: The confidence value of extraction of the value.
  • Multientities: Boolean - Determines if multiple owners were listed as owners.
  • Foundand: Boolean - Was "and" found in the vehicle owner.
  • Foundor: Boolean - Was "or" found in the vehicle owner.
  • Coowner: Name of the suspected co-owner.
  • Business: Boolean - Determines if a business entity owns the vehicle.
  • Suffix: Boolean - Determines if the owner name includes a suffix (e.g., Jr, Sr, III).
  • Multiline: Boolean - Determines if the owner names are on multiple lines.
  • Validatedvin: Boolean - Determines if the VIN was found on the document.
  • type: String - How was the information found on the document?
  • ValidatedTitleDate: Boolean - Determines if the title is current based on the provided title date.

Additional Information

  • The API is intended to answer the questions: Is this title current? Is the VIN correct? Is the owner on the title document? Are there co-owners in addition to the owner?
  • Watch words are searched for in the document and flagged if they appear. The response for watch words will be "watch_"+term.

Limitations

  • When using a byte string, the original file must be in JPEG or PNG format and cannot exceed 5 MB.

History

Endpoint

POST /history

Description

This API provides the ability to extract vehicle history based on the vehicle VIN number.

Request Format

Headers

  • Content-Type: application/json
  • authorizationToken: <your_api_key>
{
    "Content-Type": "application/json",
    "authorizationToken": "AUTH_TOKEN_HERE"
}

Body

{
  "vin": "string"
}

Parameters

Parameter Type Required Description
vin string Yes 17-digit alphanumeric vehicle identification number.

Responses

Success Response

Code: 200 OK

{
  "code": 200,
  "message": "Success",
  "responseData": {
    "vin": "KL4CJCSB7EB541370",
    "titles": [
      {
        "vin": "KL4CJCSB7EB541370",
        "state": "SC",
        "date": "2023-01-25",
        "meter": "90748",
        "meter_unit": "M",
        "current": true
      },
      // ... additional title entries
    ],
    "checks": [],
    "jsi": [],
    "clean": true,
    "salvage": [],
    "accidents": [],
    "thefts": [],
    "lie": []
  }
}

Error Responses

Code: 403 Forbidden

{
  "detail": "You do not have permission to perform this action."
}

Code: (Unspecified)

{
  "detail": "Error - no_records"
}

Detailed Field Descriptions

  • titles: List of previous titles
  • vin: String - Vehicle Identification Number
  • state: String - State where the title was issued
  • date: String - Date of title issuance (YYYY-MM-DD format)
  • meter: String - Odometer reading at the time of titling
  • meter_unit: String - Unit of the odometer reading (e.g., "M" for miles)
  • current: Boolean - Indicates if this is the current title
  • checks: List of brand records
  • jsi: List of junk | salvage | insurance records
  • clean: Boolean - Determines if the title is free of records
  • salvage: List of salvage records
  • accidents: List of accident records
  • thefts: List of theft records
  • lie: List of lien | impound | export records

Additional Information

  • The API returns a comprehensive history of the vehicle based on the provided VIN.
  • An empty list for any category (e.g., checks, salvage, accidents) indicates no records of that type were found.

Limitations

  • The API requires a valid 17-digit VIN to retrieve the vehicle history.
  • The completeness of the history depends on the available records for the given VIN.