/units

Inventory Units

The Units API allows Manheim customers to manage details about the vehicles they are selling, such as description and contact details. A unit represents a vehicle that is or can be represented in inventory within Manheim for a particular seller.

Customers (sellers) can use this API to create, retrieve, or update a vehicle record within their inventory, and to retrieve a complete list of their vehicles in inventory with Manheim.

Release Notes

December 2018

Updated acceptable transmission and title branding values

October 2018

Updated acceptable values for "odometer.units", "title.brandings", and "engine.fuel" fields.

Added "title.present" field and acceptable values.

May 2017

Added "lastActiveOn" response field to indicate when a new resource such as a consignment or offering was added for the unit. Applies to all methods for retrieving consignments.

Added the "lastActiveOn" field to the UNITS.CREATED and UNITS.UPDATED events.

URLs and Environments

The base URL for the Units API is /units. This document describes each method endpoint starting with the base URL.

Actual requests will require the protocol and host URL for one of the Manheim environments:

UAT: https://uat.api.manheim.com
Production: https://api.manheim.com

See API Access and Environments for more information about Manheim API environments.

Authentication & Authorization

To use this API, you must have a Mashery API Package Key that is active with the inventory:customer scope assigned to it.
When requesting an access token for this API, use the resource owner password credentials grant type, the inventory:customer scope, and your manheim.com credentials for the username and password (note: * the manheim.com credentials must match the environment being accessed*).

The request header must include the Authorization key with a value of Basic followed by your Base64 encoded Mashery key:secret pair. Note that you must Base64 encode your Mashery key:secret. For details of how to do this refer to Preparing the Authorization Header.

Attribute	Value
Authorization	Basic
Content-Type	application/x-www-form-urlencoded
grant_type	password
username	manheim.com username (for related environment)
password	manheim.com password (for related environment)
scope	inventory:customer

Example cURL:

curl --location --request POST 'https://uat.api.manheim.com/oauth2/token.oauth2' \
--header 'Authorization: Basic aDNod2dtNDQ0NWtqenB0XXXXXXXXXXXXX=' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=password' \
--data-urlencode 'username=manheimUsername' \
--data-urlencode 'password=manheimPassword' \
--data-urlencode 'scope=inventory:customer'

For details on how to request a token and additional information on authentication and authorization, please refer to Authentication and Authorization.

Events

Events related to Units are published real time. You can subscribe to these events through the Subscriptions API. The following events are available:

Event Name	Description
UNITS.CREATED	A unit has been created
UNITS.UPDATED	Changes have been made to a unit

Add a New unit

Endpoint

POST /units

Description

This method is used to add a new unit to a customer's vehicle inventory. A unit must exist to perform other actions within the Manheim API such as requesting Orders or Offerings.

Events

When a new unit is created, a "UNITS.CREATED" event is generated. You can subscribe to this event through the Subscriptions API.

Common Return Codes

Response Code	Response Message	Possible Next Actions
201 Created	No message in the body of the request; Returns Location field in the header which contains a URL with an ID unique to that unit	No actions necessary; request was successful
400 Bad Request	ERROR: A required property is missing from the request and will be listed in the property field; unit has not been added	Check the input parameters and resubmit
401 Unauthorized	ERROR: Developer inactive	API token may be malformed or the user does not have access; check the token or contact us for API access
403 Forbidden	ERROR: HTML body contains information about the error	Check the URL or the method of the request and resubmit
404 Not Found	ERROR: HTML message contains information about the error	Check the URL or the method of the request and resubmit
409 Conflict	ERROR: A unit with the vin XXXXXXXXXXXXXXXXX specified already exists	The requested VIN has already been used for another unit; use a new VIN for creating a unit
415 Unsupported Media Type	ERROR Blank body	Check the Content-type field of the header and resubmit
596 596	ERROR: HTML body contains information about the error	Check the HTTP method and URL and resubmit

Request Parameters

Field	Type	Requirement	Description
type	String	REQUIRED	Defines the type of vehicle; accepted values are: "PASSENGER_VEHICLE" and "UNKNOWN"
subtype	String	OPTIONAL	Defines the body type of the vehicle; accepted values are: "Sedan", "Hatchback", "Convertible", "Coupe", "SUV", "Truck", "Van", "Wagon"
vin	String	REQUIRED	Vehicle identification number - typically 17 characters.
contact	-	OPTIONAL	Contact information for the seller or owner of the vehicle
contact.contactName	String	OPTIONAL	Name of contact
contact.companyName	String	OPTIONAL	Name of contact's company
contact.phone	String	OPTIONAL	Phone number for contact
contact.email	String	OPTIONAL	Email address of contact
contact.manheimAccountNumber	String	REQUIRED	The account number used to do business with Manheim - typically the Auction Access ID
customerReferenceID	String	OPTIONAL	Customer-defined ID
description	-	OPTIONAL	Description details of vehicle
description.modelYear	Integer	OPTIONAL	Vehicle year
description.make	String	OPTIONAL	Make of vehicle
description.model	String	OPTIONAL	Model of vehicle
description.trim	String	OPTIONAL	Trim of the vehicle
description.interiorColor	-	OPTIONAL	Interior color details
description.interiorColor.code	String	OPTIONAL	Code for vehicle interior color
description.interiorColor.description	String	OPTIONAL	Description of vehicle interior color
description.exteriorColor	-	OPTIONAL	Exterior color details
description.exteriorColor.code	String	OPTIONAL	Code for vehicle exterior color
description.exteriorColor.description	String	OPTIONAL	Description of vehicle exterior color
description.engine	-	OPTIONAL	Vehicle engine details
description.engine.type	Integer	OPTIONAL	Engine type; example values are: "1_CYLINDER", "2_CYLINDER", "3_CYLINDER", "4_CYLINDER", "5_CYLINDER", "6_CYLINDER", "7_CYLINDER", "8_CYLINDER", "10_CYLINDER", "12_CYLINDER", "ROTARY V8"
description.engine.horsepower	String	OPTIONAL	The power of the engine
description.engine.displacement	Double	OPTIONAL	Decimal value of the engine size, such as "2.5"
description.engine.fuel	String	OPTIONAL	Engine fuel type; accepted values are: "GASOLINE", "DIESEL", "ALTERNATIVE_HYBRID", "ELECTRIC"
description.transmission	String	OPTIONAL	Transmission type; accepted values are: "AUTOMATIC", "MANUAL", "CVT"
description.interiorType	String	OPTIONAL	Interior seating fabric type; accepted values are: "CLOTH", "LEATHER", "VINYL"
description.roofType	String	OPTIONAL	Describes the vehicle's roof; accepted values are: "CONVERTIBLE", "HARDTOP", "SUN_ROOF", MOON_ROOF", "T_TOP", "VINYL_ROOF"
description.driveType	String	OPTIONAL	Describes the vehicle's drivetrain; accepted values are: "2_WHEEL_DRIVE", "4_WHEEL_DRIVE", "ALL_WHEEL_DRIVE"
description.audio	String	OPTIONAL	Array of audio options; accepted values are: "AM", "FM", "CD", "CASSETTE", "SATELLITE", "PREMIUM"
description.doorCount	Integer	OPTIONAL	Number of doors; accepted values are: "2", 3", "4", "5"
description.options	-	OPTIONAL	Array of vehicle options, such as "ANTILOCK_BRAKES", "CRUISE_CONTROL", or "POWER_WINDOWS"
odometer	-	OPTIONAL	Contains odometer details
odometer.reading	Integer	OPTIONAL	Reading on odometer with a maximum value of "2147483647"
odometer.units	String	OPTIONAL	Units of measure for odometer reading; accepted values are: "MILES", "KILOMETERS", "HOURS", "K", "M", "H", "MI", "KM"
odometer.digits	Integer	OPTIONAL	Number of digits available for odometer readout
odometer.type	String	OPTIONAL	Odometer reading type; accepted values are: "DIGITAL", "ANALOG"
physicalLocation	-	OPTIONAL	Contains information about the physical location of the vehicle
physicalLocation.name	String	OPTIONAL	Name of the location, for example, the name of the dealership where the vehicle is located
physicalLocation.type	String	OPTIONAL	Type of location; accepted values are: "AT_AUCTION", "AT_DEALERSHIP"
physicalLocation.operatingLocation	-	OPTIONAL	Contains details about the physical location of the vehicle
physicalLocation.operatingLocation.href	String	OPTIONAL	URL of details about the physical location of the vehicle
physicalLocation.address	String	OPTIONAL	Address of the physical location of the vehicle
physicalLocation.city	String	OPTIONAL	City of the physical location of the vehicle
physicalLocation.state	String	OPTIONAL	State of the physical location of the vehicle
physicalLocation.zip	String	OPTIONAL	ZIP code of the physical location of the vehicle
conditionReports	-	OPTIONAL	Array of available non-Manheim condition reports for vehicle
conditionReports[#].source	String	OPTIONAL	Originating system of condition report; example values are: "DataScan", "AIM"
conditionReports[#].href	String	OPTIONAL	URL of non-Manheim condition report
condition.frameDamage	Boolean	OPTIONAL	Indicator of vehicle frame damage, accepted values are: "true", "false"
condition.priorPaint	-	OPTIONAL	Array of details about prior paint jobs performed on the vehicle
condition.priorPaint[#].description	String	OPTIONAL	Identifies the areas on the vehicle where the prior paint job was completed; accepted values are: "OVERALL VEHICLE", "BOTH_BUMPERS", "FRONT_BUMPER", "REAR_BUMPER", "LEFT_BED_SIDE", "LEFT_FENDER", "LEFT_FRONT_DOOR", "LEFT_QUARTER_PANEL", "LEFT_REAR_DOOR", "LEFT_ROCKER_PANEL", "RIGHT_BED_SIDE", "RIGHT_FENDER", "RIGHT_FRONT_DOOR", "RIGHT_QUARTER_PANEL", "RIGHT_REAR_DOOR", "RIGHT_ROCKER_PANEL"
condition.priorPaint[#].condition	String	OPTIONAL	Identifies the quality of the paint that was repaired; accepted value are: "ACCEPTABLE", "SUBSTANDARD"
title	-	OPTIONAL	Contains title information
title.number	Integer	OPTIONAL	The unique number for the title
title.state	String	OPTIONAL	State in which title was created; consists of standard 2-character state abbreviation
title.notRequired	Boolean	OPTIONAL	"true" if title is not required; "false" if required
title.receivedDate	String	OPTIONAL	Date title was received, in UTC format YYYY-MM-DD
title.location	String	OPTIONAL	The physical location of the title; accepted values are: "AT_AUCTION", "AT_DEALERSHIP", "SENT_TO_STATE", "SENT_TO_SELLER"
title.operatingLocation	-	OPTIONAL	Information about the auction where the title is located, if applicable
title.operatingLocation.href	String	OPTIONAL	URL of the auction where the title is located, if applicable
title.branding	String	OPTIONAL	Identifies the type of title; If multiple brandings are required, submit as a comma separated string. e.g. "Branding1, Branding2, Branding3"; accepted values are: "CLEAN", "CLASSIC", "SALVAGE", "TMU", "REPO", "LEMON LAW", "REBUILT", "IRREPARABLE", "POLICE/TAXI", "FIRE DAMAGE", "BOND", "OTHER", "STOLEN/THEFT RECOVERY"
title.problem	String	OPTIONAL	Identifies whether there is a problem with the title; accepted values are: "true", "false"
title.present	String	OPTIONAL	Identifies whether the title is present; accepted values are: "PRESENT", "ABSENT"
images	-	OPTIONAL	Array of images
images[#].type	String	OPTIONAL	Defines the type of image; accepted values are: "PRIMARY_IMAGE", "OTHER_IMAGE", "FRONT_LEFT", "REAR_LEFT", "FRONT_RIGHT", "REAR_RIGHT", "WHEEL", "INTERIOR_FRONT", "DASHBOARD", "ENGINE", "ODOMETER", "INTERIOR_REAR", "MFG_TAG", "CARGO", "UNKNOWN", "DAMAGE", "WO_STICKER", "FRONT", "REAR", "REAR_FRONT_INTERIOR", "DRIVER_DOOR_PANEL", "STEERING_WHEEL", "3RD_ROW_SEAT", "SUNROOF"
images[#].href	String	OPTIONAL	URL for retrieving the image described by the value in the images[#].type field

Example JSON Request

The user would send their request to the following endpoint to Add a New Unit.

POST https://uat.api.manheim.com/units

The user would include a request similar to the following in the body of their request to Add a New Unit.

{
  "type": "PASSENGER_VEHICLE",
  "subtype": "SEDAN",
  "vin": "1FAP14P57711AA2AA",
  "contact": {
    "contactName": "John Doe",
    "companyName": "Porsche Finance",
    "phone": "555-555-5555",
    "email": "johndoe@porsche.com",
    "manheimAccountNumber": "5123101"
  },
  "customerReferenceId": "111111",
  "description": {
    "modelYear": 2014,
    "make": "Ford",
    "model": "Mustang",
    "trim": "GT Convertible 2-Door",
    "interiorColor": {
      "code": "RED",
      "description": "Red"
    },
    "exteriorColor": {
      "code": "WHITE",
      "description": "White"
    },
    "engine": {
      "type": "V8",
      "horsepower": 420,
      "displacement": 5.2,
      "fuel": "GASOLINE"
    },
    "transmission": "AUTOMATIC",
    "interiorType": "LEATHER",
    "roofType": "CONVERTIBLE",
    "driveType": "2_WHEEL_DRIVE",
    "audio": [
      "AM",
      "FM",
      "CD",
      "CASSETTE",
      "SATELLITE",
      "PREMIUM"
    ],
    "doorCount": 2,
    "options": [
      "ANTILOCK_BRAKES",
      "AIRBAG_SIDE_CURTAIN",
      "AIR_CONDITIONING",
      "AIRBAGS",
      "ALLOY_WHEELS",
      "CHILD_SEAT",
      "CHILD_SEAT_ANCHORS",
      "CRUISE_CONTROL",
      "DUAL_CLIMATE_CONTROL",
      "DVD",
      "NAVIGATION",
      "HEATED_SEATS",
      "POWER_BRAKES",
      "POWER_DOOR_LOCKS",
      "POWER_MIRRORS",
      "POWER_SEATS",
      "POWER_STEERING",
      "POWER_WINDOWS",
      "REAR_WINDOW_DEFROSTER",
      "TILT_TELESCOPE_WHEEL",
      "TINTED_GLASS"
    ]
  },
  "odometer": {
    "reading": 376,
    "units": "MILES",
    "digits": 8,
    "type": "DIGITAL"
  },
  "physicalLocation": {
        "name": "Main Street Chevrolet",
        "type": "AT_DEALERSHIP",
        "address": "3905 Main Street",
        "city": "Cambridge",
        "state": "MA",
        "zip": "02310"
  },
  "conditionReports": [
    {
      "source": "DataScan",
      "href": "http://www.manheim.com"
    }
  ]

Example JSON Response

The body of the response will be blank, but the header contains information about the unit created. The "Location" field contains a URL with the ID of the new unit that may be used in subsequent requests to view the unit or update the unit.

Example:

https://uat.api.manheim.com/units/id/ID

The ID in the example above would be replaced by a unique ID for that specific unit. The unit example above would return a URL similar to the example below.

Example "Location" URL:

https://uat.api.manheim.com/units/id/222ccff0-60bc-11e6-b072-136a8f36abcd

Update a Unit

Endpoint

POST /units/id/ID

Description

This method allows a user to update a unit in their Manheim inventory. Users may update one or more fields at a time by calling this method.

Some clients are not able to update certain fields, including "vin", "manheimAccountNumber", "contact.customerId", "contact.accountId", "contact.account.href", "customer.href", "owner.account.href", and "owner.company.href".

Events

When a unit is updated, a "UNITS.UPDATED" event is generated. You can subscribe to this event through the Subscriptions API.

Common Return Codes

Response Code	Response Message	Possible Next Actions
204 No Content	No message in the body of the request.	No actions necessary; request was successful
400 Bad Request	ERROR: A required property is missing from the request and will be listed in the property field; unit has not been updated	Check the input parameters and resubmit
401 Unauthorized	ERROR: Developer inactive	API token may be malformed or the user does not have access; check the token or contact us for API access
403 Forbidden	ERROR: HTML message containing details about the error	The URL or method may be malformed; check and resubmit the request
404 Not Found	ERROR: Blank body or HTML message containing details about the error	URL or ID may be malformed; check and resubmit the request
415 Unsupported Media Type	ERROR Blank body	Check the Content-type field of the header and resubmit
596	ERROR: HTML body contains information about the error	Check the HTTP method and URL and resubmit

Request Parameters

This method REQUIRES the ID of the unit in the URL of the request. The ID may be retrieved from the Location URL.

A user can provide any of the fields listed above with the updated value(s) in the body of the request.

Example JSON Request

Using the example above, the user could change the odometer reading of the unit by submitting the following request.

POST https://uat.api.manheim.com/units/id/222ccff0-60bc-11e6-b072-136a8f36abcd

The body of the request would be as follows:

{
   "odometer": {
    "reading": 5000
  }
}

This request would update only the "odometer.reading" field of this unit.

Example Response

The body of the request will be blank but the header will contain information about the update, such as the time the unit was updated.

Retrieve Inventory by ID

Endpoint

GET /units/id/ID

Description

This method allows a user to retrieve information about a single unit in their Manheim inventory.

Common Return Codes

Response Code	Response Message	Possible Next Actions
200 OK	Contains details about the unit requested	No actions necessary; request was successful
401 Unauthorized	ERROR: Developer inactive	API token may be malformed or the user does not have access; check the token or contact us for API access
404 Not Found	ERROR: Blank body or HTML message containing details about the error	URL or ID may be malformed; check and resubmit the request
596	ERROR: HTML body contains information about the error	Check the HTTP method and URL and resubmit

Request Parameters

This method REQUIRES the ID of the unit in the URL of the request. The ID may be retrieved from the Location URL.

Example JSON Request

The body of this method is blank. The user only needs to make a request to the endpoint to retrieve information about a specific ID.

The following is an example of a request to Retrieve Inventory by ID.

GET https://uat.api.manheim.com/units/id/e5e7e17c-ee7d-47cd-92c0-0f54dab3XXXX

Response Parameters

This method will return the fields found in the table below in addition to the fields used in the request to Add a Unit. Note that all fields may not be present in each response.

Field	Type	Description
href	String	URL of the request submitted by the user
active	Boolean	"true" or "false" value to identify whether the unit is an active listing
updatedOn	DateTime	Date and time of the last update to the unit in UTC format of YYYY-MM-DDTHH:MM:SSSZ
createdOn	DateTime	Date and time of the creation of the unit in UTC format of YYYY-MM-DDTHH:MM:SSSZ
lastActiveOn	DateTime	Date and time a resource such as a consignment or offering was last added for this unit in UTC format of YYYY-MM-DDTHH:MM:SSSZ
manheimAccountNumber	String	Manheim account identifier for the customer
contact	-	Contains customer details
contact.accountId	String	Manheim account identifier for the customer
contact.customerId	String	OVC Company ID of the manheimAccountNumber on the unit
physicalLocation	-	Contains physical location information
physicalLocation.country	String	Country of the physical location of the vehicle
vehicle	-	Contains a link to information about the vehicle
vehicle.href	String	URL of vehicle information, including valuations, serial number, and images
title.href	String	URL of vehicle title details
customer	-	Contains customer details
customer.href	String	URL of customer details
account	-	Contains a link to retrieve information about the account
account.href	String	URL for customer account information
owner	-	Contains details about the owner of the vehicle
owner.manheimAccountNumber	Integer	Account number of the owner of the vehicle
owner.account	-	Contains a link to the customer ID for the owner of the vehicle
owner.account.href	String	URL for the customer account of the owner of the vehicle
owner.company	-	Contains a link to the customer account for the company that owns the vehicle
owner.company.href	String	URL for the customer account for the company of that owns the vehicle
orders	-	Contains a reference to the unit for the vehicle
orders.href	String	URL for use in the Orders API
offerings	-	Contains an array of information about various offerings for the unit
offerings.href	String	URL for use in the Offerings API
consignments	-	Contains an array of information about the unit as a consignment for sale
consignments.href	String	URL for use in the Consignments API
media	-	Collection of Images/Files/Fyuse for offsite vehicles
media.href	String	URL for use in the Media API
disclosures	-	Offsite disclosures for vehicle condition
disclosures.href	String	URL for use in the Disclosures API
ownerReferences	-	Contains various seller provided data points
ownerReferences.href	String	URL for use in the Owner References API
sellerDescriptions	-	Contains the seller provided vehicle description
sellerDescriptions.href	String	URL for use in the Seller Descriptions API
announcements	-	Contains announcements for offsite vehicles
announcements.href	String	URL for use in the Announcements API
vehicleLocations	-	Contains vehicle location for offsite vehicles
vehicleLocations.href	String	URL for use in the Vehicle Locations API
lifecycles	-	Contains a block of information about a series of processing steps that each vehicle goes through as it moves about the system
lifecycles.href	String	URL with information about a series of processing steps that each vehicle goes through as it moves about the system
inventoryUnitProviders	-	Contains inventoryUnitProviders details
inventoryUnitProviders.href	String	URL of inventoryUnitProviders details
prices	-	Contains prices details
prices.href	String	URL of prices details

Example JSON Response

The user would receive a response similar to the following when submitting a successful request to Retrieve Inventory by ID.

{
    "href": "https://uat.api.manheim.com/units/id/02e8a946-7890-11e8-8948-1bb3bb79cccc",
    "vin": "1FA83ST1832318AT2",
    "type": "PASSENGER_VEHICLE",
    "active": true,
    "updatedOn": "2018-06-25T15:54:15.522Z",
    "createdOn": "2018-06-25T15:54:15.522Z",
    "lastActiveOn": "2018-06-25T15:54:15.422Z",
    "contact": {
        "customerId": "444444",
        "accountId": "555555",
        "contactName": "depot",
        "companyName": "CAR DEPOT",
        "phone": "(313) 333-3333",
        "manheimAccountNumber": "5123112"
    },
    "vehicle": {
        "href": "https://uat.api.manheim.com/vehicles/id/f43192e3-7e69-469a-b320-152dca30cccc"
    },
    "description": {
        "modelYear": 2011,
        "make": "Ford",
        "model": "Escape",
        "trim": "Limited",
        "transmission": "Automatic",
        "interiorType": "Leather",
        "doorCount": 0,
        "audio": [
            "AM",
            "FM",
            "CD"
        ],
        "options": [
            "ANTILOCK_BRAKES",
            "AUTOMATIC_TRANSMISSION",
            "AIR_BAG_DUAL",
            "DUAL_CLIMATE_CONTROL",
            "POWER_SEATS",
            "POWER_WINDOWS",
            "HEATED_SEAT_DRIVER_AND_PASSENGER",
            "NAVIGATIONAL_SYSTEM",
            "5_PASSENGER",
            "50_STATE_EMISSIONS"
        ],
        "exteriorColor": {
            "code": "8",
            "description": "Gray"
        },
        "interiorColor": {
            "code": ""
        }
    },
    "odometer": {
        "reading": 35996,
        "units": ""
    },
    "physicalLocation": {
        "type": "AT_AUCTION",
        "address": "4900 Buffington Rd",
        "city": "College Park",
        "state": "GA",
        "country": "US",
        "zip": "30349"
    },
    "title": {
        "state": "CA",
        "location": "AT_AUCTION",
        "branding": "Not Specified"
    },
    "customer": {
        "href": "https://uat.api.manheim.com/contacts/id/112955cf-22a9-4e92-9300-66a06145cccc/company"
    },
    "account": {
        "href": "https://uat.api.manheim.com/contacts/id/112955cf-22a9-4e92-9300-66a06145cccc/account"
    },
    "owner": {
        "manheimAccountNumber": "5123112",
        "account": {
            "href": "https://uat.api.manheim.com/contacts/id/112955cf-22a9-4e92-9300-66a06145cccc/account"
        },
        "company": {
            "href": "https://uat.api.manheim.com/contacts/id/112955cf-22a9-4e92-9300-66a06145cccc/company"
        }
    },
    "orders": {
        "href": "https://uat.api.manheim.com/orders/unit/02e8a946-7890-11e8-8948-1bb3bb79cccc"
    },
    "offerings": {
        "href": "https://uat.api.manheim.com/offerings/unit/02e8a946-7890-11e8-8948-1bb3bb79cccc"
    },
    "consignments": {
        "href": "https://uat.api.manheim.com/consignments/unit/02e8a946-7890-11e8-8948-1bb3bb79cccc"
    },
    "lifecycles": {
        "href": "https://uat.api.manheim.com/lifecycles/unit/02e8a946-7890-11e8-8948-1bb3bb79cccc"
    }
}

Retrieve All Inventory

Endpoint

GET /units/mine

Description

This method allows a user to view their entire inventory of units associated with their "customerId". The response has a default limit of 25 units per page, but this value may be adjusted with a query parameter in the URL as explained in the "Request Parameters" section for this method.

Common Return Codes

Response Code	Response Message	Possible Next Actions
200 OK	Contains details about the unit(s) requested	No actions necessary; request was successful
401 Unauthorized	ERROR: Developer inactive	API token may be malformed or the user does not have access; check the token or contact us for API access
404 Not Found	ERROR: HTML message containing details about the error	URL may be malformed; check and resubmit the request
596	ERROR: HTML body contains information about the error	Check the HTTP method and URL and resubmit

Request Parameters

The user must call the endpoint to Retrieve All Inventory using the "token" for the account which the units belong to.

The following table provides OPTIONAL query string parameters that may be used in the request.

Parameter	Type	Notes
limit	Integer	Changes the number of units returned per page

Example JSON Request

The user would make a call similar to the following to set a specific limit on the number of units returned.

GET https://uat.api.manheim.com/units/mine?limit=2

Response Parameters

The JSON response for this method contains a collection of unit details as a block under the field "items".

This method will return the fields found in the table below in addition to the fields used in the request to Add a Unit and the fields in the request to Retrieve Inventory by ID.

Field	Type	Description
limit	Integer	Defines the number of results to be displayed per page with a default of "25"
first	-	Contains an array of details about the first page of results
first.href	String	URL to view the first page of results
previous	-	Contains an array of details about the previous page of results
previous.href	String	URL to view the previous page of results
next	-	Contains an array of details about the next page of results
next.href	String	URL to view the next page of results

Example JSON Response

If a user made a request to the above endpoint, they would receive a response similar to the following.

{
  "items": [
    {
      "href": "https://uat.api.manheim.com/units/id/558aa7fa-6328-11e6-97f3-2bc18d25XXXX",
      "vin": "4T1TEWSHGF468XXXX",
      "type": "PASSENGER_VEHICLE",
      "active": true,
      "updatedOn": "2016-08-15T20:39:16.641Z",
      "createdOn": "2016-08-15T20:39:16.641Z",
      "contact": {
        "customerId": "1234567",
        "accountId": "1234567",
        "manheimAccountNumber": "5123135"
      },
      "customer": {
        "href": "https://uat.api.manheim.com/contacts/id/2000b984-194a-4815-a55c-89ee554eXXXX/company"
      },
      "account": {
        "href": "https://uat.api.manheim.com/contacts/id/2000b984-194a-4815-a55c-89ee554eXXXX/account"
      },
      "orders": {
        "href": "https://uat.api.manheim.com/orders/unit/558aa7fa-6328-11e6-97f3-2bc18d25XXXX"
      },
      "offerings": {
        "href": "https://uat.api.manheim.com/offerings/unit/558aa7fa-6328-11e6-97f3-2bc18d25XXXX"
      },
      "subscriptions": {
        "href": "https://uat.api.manheim.com/subscriptions/unit/558aa7fa-6328-11e6-97f3-2bc18d25XXXX"
      },
      "consignments": {
        "href": "https://uat.api.manheim.com/consignments/unit/558aa7fa-6328-11e6-97f3-2bc18d25XXXX"
      },
      "lifecycles": {
        "href": "https://uat.api.manheim.com/lifecycles/unit/558aa7fa-6328-11e6-97f3-2bc18d25XXXX"
      }
    },
    {
      "href": "https://uat.api.manheim.com/units/id/543498f2-6328-11e6-8047-09a1c2eaXXXX",
      "vin": "1G7CVG7354KJ1XXXX",
      "type": "PASSENGER_VEHICLE",
      "active": true,
      "updatedOn": "2016-08-15T20:39:14.402Z",
      "createdOn": "2016-08-15T20:39:14.402Z",
      "contact": {
        "customerId": "1234567",
        "accountId": "1234567",
        "manheimAccountNumber": "5123135"
      },
      "customer": {
        "href": "https://uat.api.manheim.com/contacts/id/6966d018-1653-427d-96a9-b3c7e6ecXXXX/company"
      },
      "account": {
        "href": "https://uat.api.manheim.com/contacts/id/6966d018-1653-427d-96a9-b3c7e6ecXXXX/account"
      },
      "orders": {
        "href": "https://uat.api.manheim.com/orders/unit/543498f2-6328-11e6-8047-09a1c2eaXXXX"
      },
      "offerings": {
        "href": "https://uat.api.manheim.com/offerings/unit/543498f2-6328-11e6-8047-09a1c2eaXXXX"
      },
      "subscriptions": {
        "href": "https://uat.api.manheim.com/subscriptions/unit/543498f2-6328-11e6-8047-09a1c2eaXXXX"
      },
      "consignments": {
        "href": "https://uat.api.manheim.com/consignments/unit/543498f2-6328-11e6-8047-09a1c2eaXXXX"
      },
      "lifecycles": {
        "href": "https://uat.api.manheim.com/lifecycles/unit/543498f2-6328-11e6-8047-09a1c2eaXXXX"
      }
    }
  ],
  "href": "https://uat.api.manheim.com/units/mine?limit=2",
  "limit": 2,
  "next": {
    "href": "https://uat.api.manheim.com/units/mine?direction=next&id=543498f2-6328-11e6-8047-09a1c2eaXXXX&limit=2"
  }
}

Event Message Examples

The following examples show JSON event messages related to the Units API. You can receive these events using the Subscriptions API.

UNITS.CREATED

{
  "subscriber": {
    "href": "https://uat.api.manheim.com/subscribers/id/1788b8be-0f4a-11ed-cec4-2d32fe7965c5"
  },
  "href": "https://uat.api.manheim.com/events/id/cbaa4b00-1350-11ed-0c69-ab6a233a49e5",
  "eventType": "UNITS.CREATED",
  "subscription": {
    "href": "https://uat.api.manheim.com/subscriptions/id/ed8bc7edf81f3cd89074be77e6dfff6e"
  },
  "body": {
    "lastActiveOn": "2022-08-03T17:22:04.670Z",
    "description": {
      "interiorColor": {
        "description": "Blue"
      },
      "transmission": "AUTOMATIC",
      "exteriorColor": {
        "description": "Red"
      },
      "trim": "4D SEDAN",
      "engine": {
        "fuel": "GASOLINE",
        "type": "4_CYLINDER"
      },
      "driveType": "2_WHEEL_DRIVE",
      "model": "LS 4C",
      "modelYear": 2003,
      "make": "SATURN",
      "doorCount": 4
    },
    "media": {
      "href": "https://uat.api.manheim.com/inventory/media/unit/cb4125d0-1350-11ed-b35b-05caac2bc7e7"
    },
    "type": "PASSENGER_VEHICLE",
    "inventoryUnitProviders": {
      "href": "https://uat.api.manheim.com/inventory/unit-providers/unit/cb4125d0-1350-11ed-b35b-05caac2bc7e7"
    },
    "createdOn": "2022-08-03T17:22:04.670Z",
    "vehicle": {
      "href": "https://uat.api.manheim.com/vehicles/id/0578e8d1-8764-4db0-c1e4-dd1331974525"
    },
    "ownerReferences": {
      "href": "https://uat.api.manheim.com/ownerReferences/unit/cb4125d0-1350-11ed-b35b-05caac2bc7e7"
    },
    "sellerDescriptions": {
      "href": "https://uat.api.manheim.com/descriptions/seller/unit/cb4125d0-1350-11ed-b35b-05caac2bc7e7"
    },
    "contact": {
      "accountId": "21xxxxxx",
      "companyName": "VISIONMOTORS",
      "manheimAccountNumber": "5xxxxxx",
      "customerId": "48xxxxx"
    },
    "vin": "1G8JU54F03Y512104",
    "href": "https://uat.api.manheim.com/units/id/cb4125d0-1350-11ed-b35b-05caac2bc7e7",
    "prices": {
      "href": "https://uat.api.manheim.com/prices/unit/cb4125d0-1350-11ed-b35b-05caac2bc7e7"
    },
    "offerings": {
      "href": "https://uat.api.manheim.com/offerings/unit/cb4125d0-1350-11ed-b35b-05caac2bc7e7"
    },
    "odometer": {
      "reading": 175490,
      "units": "MILES"
    },
    "manheimAccountNumber": "5xxxxxx",
    "active": true,
    "updatedOn": "2022-08-03T17:22:04.670Z",
    "lifecycles": {
      "href": "https://uat.api.manheim.com/lifecycles/unit/cb4125d0-1350-11ed-b35b-05caac2bc7e7"
    },
    "vehicleLocations": {
      "href": "https://uat.api.manheim.com/vehicleLocations/unit/cb4125d0-1350-11ed-b35b-05caac2bc7e7"
    },
    "application": {
      "clientCode": "CAFS - manheim_concierge",
      "description": "App Version 1.0.277-769",
      "source": "MANEX"
    },
    "orders": {
      "href": "https://uat.api.manheim.com/orders/unit/cb4125d0-1350-11ed-b35b-05caac2bc7e7"
    },
    "disclosures": {
      "href": "https://uat.api.manheim.com/disclosures/unit/cb4125d0-1350-11ed-b35b-05caac2bc7e7"
    },
    "consignments": {
      "href": "https://uat.api.manheim.com/consignments/unit/cb4125d0-1350-11ed-b35b-05caac2bc7e7"
    },
    "announcements": {
      "href": "https://uat.api.manheim.com/inventory/announcements/unit/cb4125d0-1350-11ed-b35b-05caac2bc7e7"
    },
    "account": {
      "href": "https://uat.api.manheim.com/contacts/id/2d2f4ea4-160a-5cf0-8049-782d496eb838/account"
    },
    "customer": {
      "href": "https://uat.api.manheim.com/contacts/id/2d2f4ea4-160a-5cf0-8049-782d496eb838/company"
    }
  },
  "createdOn": "2022-08-03T17:22:05.359Z"
}

UNITS.UPDATED

{
  "subscriber": {
    "href": "https://uat.api.manheim.com/subscribers/id/1788b8be-0f4a-11ed-cec4-2d32fe7965c5"
  },
  "href": "https://uat.api.manheim.com/events/id/93d9dc30-1360-11ed-b87d-0b91a3735c6e",
  "eventType": "UNITS.UPDATED",
  "subscription": {
    "href": "https://uat.api.manheim.com/subscriptions/id/ed8bc7edf81f3cd89074be77e6dfff6e"
  },
  "body": {
    "lastActiveOn": "2022-08-03T19:15:03.194Z",
    "description": {
      "interiorColor": {
        "description": "Blue"
      },
      "transmission": "AUTOMATIC",
      "exteriorColor": {
        "description": "Red"
      },
      "trim": "4D SEDAN",
      "engine": {
        "fuel": "GASOLINE",
        "type": "4_CYLINDER"
      },
      "driveType": "2_WHEEL_DRIVE",
      "model": "LS 4C",
      "modelYear": 2003,
      "make": "SATURN",
      "doorCount": 4
    },
    "media": {
      "href": "https://uat.api.manheim.com/inventory/media/unit/cb4125d0-1350-11ed-b35b-05caac2bc7e7"
    },
    "type": "PASSENGER_VEHICLE",
    "inventoryUnitProviders": {
      "href": "https://uat.api.manheim.com/inventory/unit-providers/unit/cb4125d0-1350-11ed-b35b-05caac2bc7e7"
    },
    "createdOn": "2022-08-03T17:22:05.208Z",
    "vehicle": {
      "href": "https://uat.api.manheim.com/vehicles/id/0578e8d1-8764-4db0-c1e4-dd1331974525"
    },
    "ownerReferences": {
      "href": "https://uat.api.manheim.com/ownerReferences/unit/cb4125d0-1350-11ed-b35b-05caac2bc7e7"
    },
    "sellerDescriptions": {
      "href": "https://uat.api.manheim.com/descriptions/seller/unit/cb4125d0-1350-11ed-b35b-05caac2bc7e7"
    },
    "contact": {
      "accountId": "21xxxxxx",
      "companyName": "VISIONMOTORS",
      "manheimAccountNumber": "5xxxxxx",
      "customerId": "48xxxxx"
    },
    "vin": "1G8JU54F03Y512104",
    "href": "https://uat.api.manheim.com/units/id/cb4125d0-1350-11ed-b35b-05caac2bc7e7",
    "prices": {
      "href": "https://uat.api.manheim.com/prices/unit/cb4125d0-1350-11ed-b35b-05caac2bc7e7"
    },
    "offerings": {
      "href": "https://uat.api.manheim.com/offerings/unit/cb4125d0-1350-11ed-b35b-05caac2bc7e7"
    },
    "odometer": {
      "reading": 175495,
      "units": "MILES"
    },
    "manheimAccountNumber": "5xxxxxx",
    "active": true,
    "updatedOn": "2022-08-03T19:15:03.197Z",
    "lifecycles": {
      "href": "https://uat.api.manheim.com/lifecycles/unit/cb4125d0-1350-11ed-b35b-05caac2bc7e7"
    },
    "vehicleLocations": {
      "href": "https://uat.api.manheim.com/vehicleLocations/unit/cb4125d0-1350-11ed-b35b-05caac2bc7e7"
    },
    "application": {
      "clientCode": "CAFS - manheim_concierge",
      "description": "App Version 1.0.277-769",
      "source": "MANEX"
    },
    "orders": {
      "href": "https://uat.api.manheim.com/orders/unit/cb4125d0-1350-11ed-b35b-05caac2bc7e7"
    },
    "disclosures": {
      "href": "https://uat.api.manheim.com/disclosures/unit/cb4125d0-1350-11ed-b35b-05caac2bc7e7"
    },
    "consignments": {
      "href": "https://uat.api.manheim.com/consignments/unit/cb4125d0-1350-11ed-b35b-05caac2bc7e7"
    },
    "announcements": {
      "href": "https://uat.api.manheim.com/inventory/announcements/unit/cb4125d0-1350-11ed-b35b-05caac2bc7e7"
    },
    "account": {
      "href": "https://uat.api.manheim.com/contacts/id/2d2f4ea4-160a-5cf0-8049-782d496eb838/account"
    },
    "customer": {
      "href": "https://uat.api.manheim.com/contacts/id/2d2f4ea4-160a-5cf0-8049-782d496eb838/company"
    }
  },
  "createdOn": "2022-08-03T19:15:03.667Z"
}

Revised 6/13/2024

/units ​

Inventory Units ​

Release Notes ​

December 2018 ​

October 2018 ​

May 2017 ​

URLs and Environments ​

Authentication & Authorization ​

Events ​

Add a New unit ​

Endpoint ​

Description ​

Events ​

Common Return Codes ​

Request Parameters ​

Example JSON Request ​

Example JSON Response ​

Update a Unit ​

Endpoint ​

Description ​

Events ​

Common Return Codes ​

Request Parameters ​

Example JSON Request ​

Example Response ​

Retrieve Inventory by ID ​

Endpoint ​

Description ​

Common Return Codes ​

Request Parameters ​

Example JSON Request ​

Response Parameters ​

Example JSON Response ​

Retrieve All Inventory ​

Endpoint ​

Description ​

Common Return Codes ​

Request Parameters ​

Example JSON Request ​

Response Parameters ​

Example JSON Response ​

Event Message Examples ​

UNITS.CREATED ​

UNITS.UPDATED ​

/units

Inventory Units

Release Notes

December 2018

October 2018

May 2017

URLs and Environments

Authentication & Authorization

Events

Add a New unit

Endpoint

Description

Events

Common Return Codes

Request Parameters

Example JSON Request

Example JSON Response

Update a Unit

Endpoint

Description

Events

Common Return Codes

Request Parameters

Example JSON Request

Example Response

Retrieve Inventory by ID

Endpoint

Description

Common Return Codes

Request Parameters

Example JSON Request

Response Parameters

Example JSON Response

Retrieve All Inventory

Endpoint

Description

Common Return Codes

Request Parameters

Example JSON Request

Response Parameters

Example JSON Response

Event Message Examples

UNITS.CREATED

UNITS.UPDATED