Hypermedia API

HTTP Methods and JSON Objects

Manheim's core third-party integration is a suite of Hypermedia APIs, where each application resource is referenced by a URL. An API consumer can invoke a URL to manage the resource it references, using standard HTTP methods. The response returned may then contain other URLs that represent related aspects of the application.

For each resource URL, the domain indicates the API environment. Manheim maintains a production environment at api.manheim.com and a pre-production environment at integration1.api.manheim.com.

Following the URL domain, the top-level directory indicates the API, and subdirectories further specify the method being called. Each API method may require a JSON object as input, return a JSON object as output, or do both.

For information about applying for access to Manheim's APIs, see the article API Access and Environments.

Example Resource Requests

The following examples show requests for a list of valuations associated with a particular Vehicle Identification Number (VIN). Each request combines the GET http method with a resource URL.

Example Request - Production

GET https://api.manheim.com/valuations/vin/5NPDH4AEXFH617834?odometer=30100&region=se&color=silver

• The URL's domain indicates that the production API environment api.manheim.com is being accessed.
• The top-level directory indicates that the valuations API is being accessed.
• The subdirectories indicate that the request should retrieve any valuations matching the vin, odometer, region, and color specified.

Example Request - Pre-Production

GET https://integration1.api.manheim.com/valuations/vin/5NPDH4AEXFH617834?odometer=30100&region=se&color=silver

This request is the same as described in the first example, except that:

• The URL's domain indicates that the pre-production API environment integration1.api.manheim.com is being accessed.

Response Status Codes

Each API request will return an HTTP status code. If an error occurs, it will be identified by an HTTP error code, possibly coupled with a JSON object that contains additional information.

The 'href' Property

Each resource is represented as a JSON object, and each object has an href property that contains the resource's URL.

An API consumer would use the following API call to create a new inventory unit. With the API call, the consumer would pass a JSON object defining the inventory unit's properties.

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

The API call would return a JSON object similar to the following. The href property contains the URL with the inventory unit's unique ID, namely "1234." The API consumer could subsequently use this URL to retrieve the object with a GET call, update the object with a POST call, or delete the object with a DELETE call.

{
  "href": "https://api.manheim.com/units/id/1234",
  "vin": "19UUA56603A001754",
  ...
}

Resource Collections

Collections of resources contain their own href property, in addition to the href property for each item in the collection.

An API consumer would use the following API call to retrieve all of the consumer's inventory units.

GET https://api.manheim.com/units/mine

The API call would return a JSON object similar to the following. The top-level href property corresponds to the collection, and the nested href property corresponds to the first element in the collection. In this case, the first inventory unit has the ID of "1234."

{
  "href": “https://api.manheim.com/units/mine”,
  "items": [
    {
      "href": "https://api.manheim.com/units/id/1234",
      "vin": "19UUA56603A001754",
      ...
    }
  ]
}

Resource Relationships

As the example above shows, it is very common for a resource to have a logical relationship with other resources. This relationship is expressed in the contents of that resource's JSON object, which includes URL's to the related resources and collections of resources.

For example, a consignment is associated with an inventory unit, therefore the inventory unit's URL is contained in the consignment's JSON object, and vice versa.

The following API call would retrieve the consignment with the unique ID of "9876."

GET https://api.manheim.com/consignments/id/9876

The API call would return a JSON object similar to the following. The top-level href property refers to the consignment, and the nested href property refers to the associated inventory unit.

{
  "href": "https://api.manheim.com/consignments/id/9876",
  "status": "CHECKED_IN",
  ...
  "unit": {
    "href": "https://api.manheim.com/units/1234"
  }
}

The relationship can also be seen in the API call to retrieve the inventory unit.

GET https://api.manheim.com/units/id/1234

The JSON object that is returned contains the inventory unit's URL in the top-level href property, and the associated consignment is referenced in the nested href property.

{
  "href": "https://api.manheim.com/units/id/1234",
  "vin": "19UUA56603A001754",
  ...
  "consignments": {
    "href": "https://api.manheim.com/consignments/unit/1234"
  }
}

NOTES

• The existence of the consignments property within the inventory unit's JSON property does not guarantee that any consigments actually exist for this inventory unit. Navigating to this URL may return a 404 NOT FOUND error if a consignment has not yet been created for the inventory unit.

• Manheim strongly encourages using the URL's in the form in which they are returned. If your business needs require your building complicated regular expressions to parse href values and construct new URL's, please contact us. Your business needs may present an opprotunity for Manheim to improve the API.

Expanding Related Resources

Instead of retrieving related resources iteratively, an API consumer can "expand" the related resources in the initial API call. The expand query parameter offers the API consumer an optimization, reducing multiple API calls into a single call.

The following API call expands the inventory unit associated with Consignment #9876.

GET https://api.manheim.com/consignments/id/9876?expand=unit

The call returns a JSON object for the consignment with the complete inventory unit nested inside, including the unit's VIN.

{
  "href": "https://api.manheim.com/consignments/id/9876",
  "status": "CHECKED_IN",
  ...
  "unit": {
    "href": "https://api.manheim.com/units/1234",
    "vin": "19UUA56603A001754",
    ...
  }
}

Multiple related resources can be expanded in one API call, by providing a comma-separated list to the expand query parameter.