/transactions

Sales

Overview

The Sales API is intended for Manheim’s seller customers to retrieve the details about their sale transactions at Manheim auctions. This API provides the seller side view of the transaction.

This document describes the contract and resources provided by the Sales API. This API is RESTful and provides access to resources via URI paths (aka endpoints). To use the RESTful contract, your application will have to make HTTP GET requests to the desired endpoints. The response payload content type is application/json. The contract is intended for Manheim’s seller customers who wish to integrate their application/system with Sales API for their sale related transactions.

URLs and Environments

The base URL for the Sales API is /transactions. This document describes each method endpoint starting with this base URL.

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

Pre-Production: 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 client credentials grant type and the inventory:customer scope.

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	client_credentials
scope	inventory:customer

Example cURL:

curl --location --request POST 'https://integration5.api.manheim.com/oauth2/token.oauth2' \
--header 'Authorization: Basic aDNod2dtNDQ0NWtqenB0XXXXXXXXXXXXX=' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--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.

Endpoints (HTTP GET Requests) are listed below. Information about each sale transaction is encoded within a JSON object in the API response.

1. Retrieve sales transactions by Customer, Auction & VIN

Endpoint

GET  /transactions/customer/{ID}/auction/{auctionCode}/vin/{VIN}

Description

The {ID} placeholder in the URL should be replaced with the customer’s auction access dealer number.
The {auctionCode} placeholder should be replaced with the desired Manheim auction location code.
The {VIN} placeholder should be replaced with the vehicle's 17-digit vehicle identification number.

2. Retrieve sales transactions for a Manheim seller customer by Customer ID

Endpoint

GET  /transactions/customer/{ID}

Description

The {ID} placeholder in the URL should be replaced with the seller customer’s auction access dealer number.

3. Retrieve sales transactions by Customer, Auction & SaleKey

Endpoint

GET /transactions/customer/{ID}/auction/{auctionCode}/saleYear/{saleYear}/saleNumber/{saleNumber}/laneNumber/{laneNumber}/runNumber/{runNumber}

Description

The {ID} placeholder in the URL should be replaced with the seller customer’s auction access dealer number.
The {auctionCode} placeholder should be replaced with the desired Manheim auction location code.
The {saleYear} placeholder should be replaced with the 4-digit sale year, e.g.: 2017.
The {saleNumber} placeholder should be replaced with the 2-digit sale number, e.g.: 11.
The {laneNumber} placeholder should be replaced with the 2-digit lane number, e.g.: 45.
The {runNumber} placeholder should be replaced with the 4-digit run number, e.g.: 0001.

Common Return Codes

Response Code	Description	Possible Next Actions
200 OK	The request completed successfully; the response includes the transactions in JSON representation	No action necessary
400 Bad Request	ERROR: Response is blank or message contains details about the parameter that is invalid or missing	If the response is blank, the request may be malformed or if there is a message, a parameter is missing or invalid; correct and resubmit
401 Unauthorized	ERROR: Access denied due to incorrect credentials, malformed API token, or because user does not have access	Validate the token or contact us for API access
403 Forbidden	ERROR: The server refused to authorize the request. The authentication credentials were provided in the request, but the server considers them insufficient to grant access	User is authenticated, but doesn’t have sufficient privileges to access the requested resource
404 Not Found	ERROR: The requested resource did not exist, or no data match found for the specified input parameters in the request	Modify request and resubmit
500 Server Error	ERROR: An unexpected condition that prevented the requested transactions from being retrieved; the response may include details about the error's cause	Response may contain details about what went wrong

Request Parameters

In order to retrieve sales transactions for a Manheim seller customer by Customer Id, Auction and VIN:

GET  /transactions/customer/{ID}/auction/{auctionCode}/vin/{VIN}

This method requires the customer ID, auction code, and VIN in the request URL.

Parameter	Type	Requirement	Description
customer	String	Required	Customer’s auction access dealer number
auction	String	Required	Manheim facilitating auction code
vin	String	Required	Vehicle's 17-digit identification number

In order to retrieve sales transactions for a Manheim seller customer by Customer ID:

GET  /transactions/customer/{ID}

The only required parameter is customer ID in this endpoint:

Parameter	Type	Requirement	Description
customer	String	Required	Customer’s auction access dealer number

For the above endpoint, the user may also use available OPTIONAL query parameters from the table below.

Optional Request Parameters

Field	Type	Description
startDate	Date	DDate in ISO format(yyyy-MM-dd) from which the API should start pulling the transactions. Always works in conjunction with endDate. If not passed in the request, it defaults to 7 days prior. Maximum window allowed between startDate and endDate is 30 days per API call.
endDate	Date	Date in ISO format(yyyy-MM-dd) up to which the API should consider pulling the transactions. Always works in conjunction with startDate. If not passed in the request, it defaults to today. Maximum window allowed between startDate and endDate is 30 days per API call.
purchaseStartDate	Date	Date in ISO format(yyyy-MM-dd) from which the API should start pulling the SOLD transactions only. Always works in conjunction with purchaseEndDate. If not passed in the request, this filter doesn’t have a default value, hence wouldn’t get applied. Maximum window allowed is 30 days per API call.
purchaseEndDate	Date	Date in ISO format(yyyy-MM-dd) up to which the API should consider pulling the SOLD transactions only. Always works in conjunction with purchaseStartDate. If not passed in the request, this filter doesn’t have a default value, hence wouldn’t get applied. Maximum window allowed is 30 days per API call.
auction	String	Manheim auction facility at which the seller transaction was performed; defaults to all auctions if omitted in the request
limit	Integer	Number of sales transaction records which may be returned in a single page; defaults to 25 if omitted and accepted values may be any positive numeric value between 1 and 500
start	Integer	Allows the response to begin at a certain record number

NOTE:

For this endpoint, API calls would work either by purchaseStartDate/purchaseEndDate combination OR startDate/endDate combination. Both of these combinations can’t be applied together in a single request.
If startDate/endDate are not passed in the request, the range defaults to the last 7 days. Maximum window allowed between startDate and endDate is 30 days per API call. It is highly recommended to keep the window very small(preferably 1 day) between startDate and endDate to avoid paging through a huge response.
purchaseStartDate/purchaseEndDate don’t have default values like startDate/endDate. Hence, if only sold transactions are to be pulled, purchaseStartDate/purchaseEndDate need to be present in the request meeting all the necessary date validations.

Recommendations:

If you are planning to call the above endpoint, it is highly recommended to make the API call for as small window(time frame) as possible for optimal performance and optimal response time from the API.
The preferred approach is to make the API call for a single purchase transaction at a time using either of the endpoints below (as applicable):
- Customer ID, auction code, and VIN
- Customer ID, auction code, and Sale Key (combination of sale year, sale number, lane number and run number)

In order to retrieve sales transactions for a Manheim seller customer by Customer Id, Auction and SaleKey:

GET /transactions/customer/{ID}/auction/{auctionCode}/saleYear/{saleYear}/saleNumber/{saleNumber}/laneNumber/{laneNumber}/runNumber/{runNumber}

This method requires the following fields in the request URL.

Parameter	Type	Requirement	Description
customer	String	REQUIRED	customer’s auction ID
auction	String	REQUIRED	Manheim auction location code
saleYear	Integer	REQUIRED	vehicle's 17-digit vehicle identification number
saleNumber	Integer	REQUIRED	2-digit sale number, e.g.: 11
laneNumber	Integer	REQUIRED	2-digit lane number, e.g.: 45
runNumber	Integer	REQUIRED	4-digit run number, e.g.: 0001

Sample Requests

Here is an example of a valid API call :

https://api.manheim.com/transactions/customer/5000000

Note : There are no query parameters specified in this sample endpoint. As also described in the aforementioned table for optional query parameters, this request would pull :

max 25 transactions (default value for limit)
for the last 7 days (default search window if startDate and endDate are missing in the request)
at all Manheim auctions (default value for auction)
including all applicable vehicles that are checked-in / offered for sale / sold

The preferred approach is to make the API call to retrieve only what is needed for better performance and response time.

More Examples

The following samples showcase the usage of several optional query parameters (as needed). The query parameters can be specified in any order.

Pull sales transactions for customer (5000000) for a specific VIN at MAA auction:

GET  /transactions/customer/5000000/auction/MAA/vin/WA1BNAFY4J2197302

Pull all sales transactions for customer (5000000) between 21-Feb-22 to 23-Feb-22:

GET  /transactions/customer/5000000?startDate=2022-02-21&endDate=2022-02-23

Pull only sold transactions for customer (5000000) between 04-Nov-21 to 05-Nov-21:

GET  /transactions/customer/5000000?purchaseStartDate=2021-11-04&purchaseEndDate=2021-11-05

Pull all sales transactions for customer (5000000) in the last 7 days at MAA auction:

GET  /transactions/customer/5000000?auction=MAA

Pull all sales transactions for customer (5000000) for the specified time window at MAA auction:

GET  /transactions/customer/5000000?startDate=2022-02-21&endDate=2022-02-23&auction=MAA

Pull only sold transactions for customer (5000000) between 25-Oct-21 to 05-Nov-21 at AAA auction:

GET  /transactions/customer/5000000?purchaseStartDate=2021-10-25&purchaseEndDate=2021-11-05&limit=25&auction=AAA

Response Details

If the request was successful and the response has sales transactions to be returned, information about the response data fields is described in the following tables. If the field is an array, items in the array may be repeated to reflect all of the data elements returned based on the request.

Field	Type	Description
href	String	Unique system-generated URL for this collection of sales transactions
limit	Integer	Number of records which may be returned in a single page; default of 25
count	Integer	Number of records returned on the page as determined by the limit
next	String	URL for the next page of sales transactions whose size is determined by the limit if the number of records exceeds the limit
previous	String	URL for the preceding page of sales transactions determined by the limit, if the preceding page exists
items	Array	Contains an array of sales transactions for the seller; each record has the fields listed in the tables below

Paging through the response

When returning a collection of resources, up to three additional properties might get included in the response object to facilitate pagination: first, previous and next. These are links that the API caller can follow to progress through the entire collection of results.

When rendering the first page of the results, first and previous links will not be included in the response.

Also as mentioned in the request parameters section, the limit parameter allows the caller to specify an arbitrary page size. The default limit is 25 and the maximum supported is 500.

For example:

GET  /transactions/customer/5000000?startDate=2021-10-10&endDate=2021-11-05&limit=10

would return

{
    "href": "https://api.manheim.com/transactions/customer/5000000?startDate=2021-10-10&endDate=2021-11-05&limit=10",
    "next": "https://api.manheim.com/transactions/customer/5000000?startDate=2021-10-10&endDate=2021-11-05&limit=10&start=10",
    "limit": 10,
    "count": 53,
    "items": [
        ……
    ]
}

And invoking the "next" link above would return:

{
    "href": "https://api.manheim.com/transactions/customer/5000000?startDate=2021-10-10&endDate=2021-11-05&limit=10&start=10",
    "first": "https://api.manheim.com/transactions/customer/5000000?startDate=2021-10-10&endDate=2021-11-05&start=10&limit=10",
    "previous": "https://api.manheim.com/transactions/customer/5000000?startDate=2021-10-10&endDate=2021-11-05&limit=10",
    "next": "https://api.manheim.com/transactions/customer/5000000?startDate=2021-10-10&endDate=2021-11-05&limit=10&start=20",
    "limit": 10,
    "count": 53,
    "items": [
        ……
    ]
}

Items Section Details

consignment

As described above, items is an array of sales transactions for the seller. Each item may contain consignment fields, as described in the table below. Values written in ALL CAPS indicate a defined list of accepted values.

Field	Type	Description
consignment	Object	Container of information describing the vehicle, physical location of the vehicle and the seller
consignment.unit	Object	Container of information describing the vehicle
consignment.unit.modelYear	Integer	The model year applicable to the vehicle
consignment.unit.make	String	The manufacturer name applicable to the vehicle
consignment.unit.model	String	The model name applicable to the vehicle
consignment.unit.vin	String	The industry-standard identification number assigned to the vehicle
consignment.unit.trim	String	The trim level of the vehicle
consignment.unit.body	String	The body type of the vehicle
consignment.unit.engineDescription	String	The type of engine in the vehicle
consignment.unit.interiorColor	String	The vehicle’s interior color
consignment.unit.exteriorColor	String	The vehicle’s exterior color
consignment.unit.odometerReading	Integer	The amount measured on the vehicle’s odometer
consignment.unit.odometerUnits	String	The unit of measurement for the vehicle’s odometer: MILES KILOMETERS HOURS
consignment.unit.groupCode	String	Code that represents a specific category with which the seller is associated at the time the vehicle is checked into auction
consignment.unit.vehicleType	String	The general class to which the vehicle belongs
consignment.unit.dispositionCode	String	Code used by auction to segregate vehicles such as: HD - Hold, UH -Upstream Hold, MX - Marshalled
consignment.unit.drivable	true or false	true if the vehicle is drivable, false otherwise
consignment.unit.keyAvailable	true or false	true if the vehicle’s key is present; false otherwise
consignment.unit.asIs	true or false	true if the vehicle is being sold as-is and is not eligible for arbitration; false if the vehicle is not being sold “as is” and is eligible for arbitration if necessary
consignment.unit.salvage	true or false	true if the vehicle has been designated as salvage, false otherwise
consignment.disclosures	Array	Array of disclosure codes pertaining to the vehicle, for example 'GUARANTEE', 'CAUTION'
consignment.unit.grade	Decimal	The current condition grade assigned to the vehicle
consignment.workOrderNumber	Integer	The Manheim identifier for a customer work request applicable to the vehicle
consignment.seller	Object	Container of information describing the seller details
consignment.seller.dealerNumber	String	The dealer number of the customer who offered the vehicle for sale
consignment.seller.dealerName	String	The name of the customer who offered the vehicle for sale
consignment.seller.dealerGroupCode	String	Code that represents a specific category with which the seller is associated
consignment.vehicleStatus	String	A status value representing the vehicle’s readiness for removal from Manheim’s auction lot
consignment.receivedDate	String	Date the vehicle was received by Manheim in "YYYYMMDD" format
consignment.scheduledSaleDate	String	Date when vehicler is registered for sale at auction
consignment.redeemedDate	String	Date when seller removes vehicle from auction lot
consignment.transferredVehicle	true or false	true if the vehicle has been transferred from another Manheim Auction Location; false otherwise
consignment.operatingLocation	Object	Container of information describing the operating location of the vehicle
consignment.operatingLocation.href	String	System-generated URL that identifies the vehicle’s associated operating location resource and provides (with appropriate authorization) access to more details about the vehicle’s operating location
consignment.operatingLocation.locationName	String	The name of the Manheim auction facilitating the vehicle’s sale
consignment.operatingLocation.locationCode	String	The identifier for the Manheim auction facilitating the vehicle’s sale
consignment.physicalLocation	Object	Container of information describing the physical location of the purchased vehicle
consignment.physicalLocation.href	String	System-generated URL that identifies the vehicle’s associated physical location resource and provides (with appropriate authorization) access to more details about the vehicle’s physical location
consignment.physicalLocation.offsite	true or false	true if the vehicle is located on Manheim premises; false otherwise
consignment.physicalLocation.locationName	String	The name assigned to the vehicle’s physical location
consignment.physicalLocation.locationCode	String	The Manheim code which uniquely identifies the physical location
consignment.physicalLocation.address	Object	Container of information describing the physical location’s address
consignment.physicalLocation.address.address1	String	The physical location’s street address
consignment.physicalLocation.address.address2	String	Additional street address line for the physical location
consignment.physicalLocation.address.city	String	The city of the physical location
consignment.physicalLocation.address.stateProvinceRegion	String	The state or province of the physical location
consignment.physicalLocation.address.country	String	The country of the physical location
consignment.physicalLocation.address.postalCode	String	The postal code of the physical location

offerings

Each item may contain offerings fields, as described in the table below. Values written in ALL CAPS indicate a defined list of accepted values.

Field	Type	Description
offerings	Array	Container holding one or more records describing an offering and the operation location
offerings[#].startDate	String	The date when the sale window applicable to the vehicle was opened
offerings[#].endDate	String	The date when the sale window applicable to the vehicle was closed
offerings[#].registrationDate	String	Date the vehicle was registered at the auction in YYYY-MM-DD format
offerings[#].currency	String	The ISO code (e.g., USD) for the money used in the purchase transaction
offerings[#].salePrice	Integer	Amount the vehicle sold for (if the vehicle has been sold)
offerings[#].soldDate	String	The date when the vehicle got sold
offerings[#].floorPrice	Integer	Minimum desired sale price of the unit
offerings[#].saleKey	Object	Container of information describing the sale of a vehicle at an auction
offerings[#].saleKey.saleYear	Integer	Year of sale of the vehicle
offerings[#].saleKey.saleNumber	Integer	Number of the sale for the vehicle at a specific auction
offerings[#].saleKey.laneNumber	Integer	Number of the lane in which the vehicle will appear at the auction
offerings[#].saleKey.runNumber	Integer	Number of the run in which the vehicle will appear in a lane at the auction
offerings[#].offeringApplication	String	The Manheim system through which the vehicle is offered for sale
offerings[#].offerMethod	String	The channel through which the vehicle is offered for sale
offerings[#].saleType	String	The sale category applicable to the vehicle
offerings[#].offeringGroupCode	String	Code that represents a specific category with which the seller is associated at the time when the vehicle is offered for sale
offerings[#].bidRestriction	String	The lowest bid the seller is willing to accept for the vehicle (for OVE only)
offerings[#].highestBidAmount	Integer	For vehicles that did not sell at auction, this is the highest bid amount a buyer made at the time the vehicle crossed the block. For vehicles sold at auction, this is the sale amount.
offerings[#].offeringStatus	String	The vehicle’s sale status
offerings[#].offeringStatusReason	String	An explanation of the vehicle’s sale status

Error response

In the event of an error, appropriate HTTP status code will be returned. Whenever possible, an error response body will also be included accompanying the HTTP status code.

For Example:

GET  /transactions/customer/5000000?startDate=2021-10-10

would return HTTP status code of “400 Bad Request”

accompanied with below error response body:

{
    "errors": [
        {
            "code": "request.endDate.missing",
            "property": "endDate",
            "message": "endDate not present in the request",
            "developerMessage": "startDate was entered but endDate is not present in the request",
            "properties": {
              "field": "endDate"
        }
    ]
}

Where errors can contain multiple errors that were found in the request.

For Example:

GET  /orders/purchases/customer/5000000?startDate=2021-10-10&limit=600

would return HTTP status code of “400 Bad Request”

accompanied with below error response body:

{
    "errors": [
        {
            "code": "request.endDate.missing",
            "property": "endDate",
            "message": "endDate not present in the request",
            "developerMessage": "startDate was entered but endDate is not present in the request",
            "properties": {
                "field": "endDate"
            }
        },
        {
            "code": "request.invalid.limit.parameter",
            "property": "limit ",
            "message": "limit in the request should be a number between 1 and 500",
            "developerMessage": "Invalid value for limit. Should be a positive number less than or equal to 500",
            "properties": {
                "field": "limit "
            }
        }
    ]
}

Example Request (Customer ID, Auction, VIN)

GET https://api.manheim.com/transactions/customer/5000000/auction/MAA/vin/WA1BNAFY4J2197302

API Response

{
    "href": "https://api.manheim.com/transactions/customer/5000000/auction/MAA/vin/WA1BNAFY4J2197302",
    "limit": 25,
    "count": 1,
    "items": [
        {
            "consignment": {
                "unit": {
                    "modelYear": 2018,
                    "make": "AUDI",
                    "model": "Q5 PRM +",
                    "vin": "WA1BNAFY4J2197302",
                    "trim": "PREMIUM +",
                    "body": "SUV",
                    "engineDescription": "4-cylinder Gas Turbo",
                    "interiorColor": "BLK",
                    "exteriorColor": "SILVER",
                    "odometerReading": 28441,
                    "odometerUnits": "MILES",
                    "groupCode": "HSAS",
                    "vehicleType": "Truck",
                    "drivable": true,
                    "asIs": false,
                    "salvage": false,
                    "disclosures": [
                      "GUARANTEE",
                      "NO TITLE"
                    ],
                    "grade": 4.2
                },
                "workOrderNumber": 1234567,
                "seller": {
                    "dealerNumber": "5000000",
                    "dealerName": "ABC Auto Sales",
                    "dealerGroupCode": "DLR"
                },
                "vehicleStatus": "Sold",
                "businessUnit": "Regular",
                "receivedDate": "2022-02-16",
                "scheduledSaleDate": "2022-02-15",
                "operatingLocation": {
                    "href": "https://api.manheim.com/locations/id/MAA",
                    "locationName": "Manheim Pennsylvania",
                    "locationCode": "MAA"
                },
                "physicalLocation": {
                    "href": "https://api.manheim.com/locations/id/MAA",
                    "offsite": false,
                    "locationName": "Manheim Pennsylvania",
                    "locationCode": "MAA",
                    "address": {
                        "address1": "1190 Lancaster Rd",
                        "city": "Manheim",
                        "stateProvinceRegion": "PA",
                        "country": "USA",
                        "postalCode": "17545-9746"
                    }
                }
            },
            "offerings": [
                {
                    "startDate": "2022-02-18T17:32:34Z",
                    "endDate": "2022-02-18T17:32:34Z",
                    "registrationDate": "2022-02-15",
                    "salePrice": 35500,
                    "soldDate": "2022-02-18T17:32:34Z",
                    "floorPrice": 0,
                    "saleKey": {
                        "saleYear": 2022,
                        "saleNumber": 10,
                        "laneNumber": 18,
                        "runNumber": 273
                    },
                    "offeringApplication": "Simulcast",
                    "offerMethod": "Auction",
                    "saleType": "WHOLE",
                    "offeringGroupCode": "ABCD",
                    "bidRestriction": "Open",
                    "highestBidAmount": 35500,
                    "offeringStatus": "Sold",
                    "offeringStatusReason": "Offer Sold"
                }
            ]
        }
    ]
}

/transactions ​

Sales ​

Overview ​

URLs and Environments ​

Authentication & Authorization ​

1. Retrieve sales transactions by Customer, Auction & VIN ​

Endpoint ​

Description ​

2. Retrieve sales transactions for a Manheim seller customer by Customer ID ​

Endpoint ​

Description ​

3. Retrieve sales transactions by Customer, Auction & SaleKey ​

Endpoint ​

Description ​

Common Return Codes ​

Request Parameters ​

Sample Requests ​

More Examples ​

Response Details ​

Paging through the response ​

Items Section Details ​

Error response ​

Example Request (Customer ID, Auction, VIN) ​

/transactions

Sales

Overview

URLs and Environments

Authentication & Authorization

1. Retrieve sales transactions by Customer, Auction & VIN

Endpoint

Description

2. Retrieve sales transactions for a Manheim seller customer by Customer ID

Endpoint

Description

3. Retrieve sales transactions by Customer, Auction & SaleKey

Endpoint

Description

Common Return Codes

Request Parameters

Sample Requests

More Examples

Response Details

Paging through the response

Items Section Details

Error response

Example Request (Customer ID, Auction, VIN)