/events

Events

Events Overview

The Events API allows consumers to retrieve past events they receive through the Subscriptions API or to create a new event.

API users may retrieve past events by their unique ID, by subscriber, by subscription, or by a specific criteria. Each method has its response encoded within a JSON object. Details for each method are provided below.

URLs and Environments

The base URL for the Events API is /events. 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:

QA: https://integration1.api.manheim.com
Pre-Production: https://uat.api.manheim.com
Production: https://api.manheim.com

See [API Access and Environments]](#/pages/accessAndEnvironments "API Access and Environments") for more information about Manheim API environments.

Create an Event

Endpoint

POST /events

Description

Allows a user to create events that other users may receive using the Subscriptions API

Common Return Codes

Manheim APIs generally return standard HTTP status codes.

201 Created: Successful response with blank body, but contains a Location URL in the header that may be used to retrieve the event in the method to Retrieve Event by ID
400 Bad Request: ERROR: Request may be missing a field; body contains information about the error
401 Unauthorized: ERROR: The authorization may be malformed; check and resubmit the request
500 Internal Server Error: ERROR: The URL may be malformed or the user may not have access; check and resubmit the request
596: ERROR: An aspect of the request may be incorrect, such as the HTTP method request; check and resubmit the request

Parameters of the JSON Request

The following fields are part of the body of the JSON request. Users may submit other fields in addition to the below as part of their request to Create an Event.

Field	Type	Requirement	Notes
body	String	REQUIRED	Contains the array of event details which may differ from one event to another
resource	String	REQUIRED	URL of the source information of the event
eventType	String	REQUIRED	Title of the event with specifics given below
relatedResources	String	OPTIONAL	One or more URLs leading to more information about an event

The eventType field contains the title of the event written in all capital letters with spaces replaced by a ".", such that "My Event" would be "MY.EVENT". The title is written with a noun that represents the subject of the event as the first word and an action that describes the event as the second word. Titles may also be written with a noun, followed by a sub-category of that noun before the verb.

NOUN.VERB Examples:

TEST.TESTED
VEHICLE.REGISTERED
USER.ANNOUNCED

NOUN.NOUN.VERB Examples:

TEST.EVENTS.TESTED
VEHICLE.CAR.REGISTERED
USER.SELLER.ANNOUNCED

Example JSON Request and Response

The following is an example of an event a user may submit to the Create an Event endpoint.

{
  "eventType": "NOUN.VERB",
  "resource": "https://api.manheim.com/units/id/997c8c3c-664b-11e6-bf0f-614176dXXXXX",
  "body": {
    "href": "https://api.manheim.com/units/id/997c8c3c-664b-11e6-bf0f-614176dXXXXX",
    "vin": "XXXXXXXXXXXXXXXXX",
    "type": "PASSENGER_VEHICLE",
    "active": true,
    "updatedOn": "2016-08-19T20:29:16.507Z",
    "createdOn": "2016-08-19T20:29:16.507Z",
    "contact": {
      "customerId": "#######",
      "accountId": "#######",
      "contactName": "John Smith",
      "companyName": "Cars by John",
      "phone": "(313) 322-####",
      "manheimAccountNumber": "#######"
    },
    "description": {
      "modelYear": 2011,
      "make": "XXXXXX",
      "model": "XXXXXXX",
      "trim": "XXXXXXXXXX",
      "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": "6325 Peachtree Dunwoody Road",
      "city": "Atlanta",
      "state": "GA",
      "zip": "30328"
    },
    "title": {
      "state": "CA",
      "location": "AT_AUCTION",
      "branding": "Not Specified"
    },
    "customer": {
      "href": "https://api.manheim.com/contacts/id/a54b8c16-0945-45bf-9f62-0a82fdeXXXXX/company"
    },
    "account": {
      "href": "https://api.manheim.com/contacts/id/a54b8c16-0945-45bf-9f62-0a82fdeXXXXX/account"
    },
    "owner": {
      "manheimAccountNumber": "#######",
      "account": {
        "href": "https://api.manheim.com/contacts/id/a54b8c16-0945-45bf-9f62-0a82fdeXXXXX/account"
      },
      "company": {
        "href": "https://api.manheim.com/contacts/id/a54b8c16-0945-45bf-9f62-0a82fdeXXXXX/company"
      }
    }
}

The successful response to Create an Event will return a "201 Created" with a blank body. The header of the JSON response will return information about the event created, such as the Location URL that may be used in the method to Retrieve Event by ID.

The Location URL in the header has the form of:

https://api.manheim.com/events/id/ID

"ID" at the end of the URL will be replaced by the ID of the event, as shown in the following example:

https://api.manheim.com/events/id/7a3f1960-6bbf-11e6-adbf-d9658aXXXXXX

Retrieve Events by ID

Endpoint

GET /events/id/ID

The ID at the end of the URL should be replaced with the unique Event ID assigned by Manheim, as shown in the example in the section above.

Description

Allows a user to view a specific event by using the associated event ID that may be retrieved from the header of the response to the method to Create an Event

Common Return Codes

Manheim APIs generally returns standard HTTP status codes.

200 OK: A successful response, which includes a JSON object containing the requested event
400 Bad Request: ERROR: The URL or ID may be malformed (response will include details); check and resubmit the request
401 Not Authorized: ERROR: The authorization may be malformed or the user may not have access; check and resubmit the request
403 Forbidden: ERROR: The HTTP request may be malformed; the response contains details about the error
404 Not Found: ERROR: The ID may not be related to an active event or it may be malformed; check and resubmit
596: ERROR: The URL may be malformed; check and resubmit

Parameters of JSON Response

Field	Notes
href	URL containing the unique ID of the event request
resource	URL of the main source of information for the event
body	Contains an array of details about the event
eventType	Title of the event
createdOn	Date and time the event was created in UTC format YYYY-MM-DDTHH:MM:SS.SSZ
updatedOn	Date and time the event was updated in UTC format YYYY-MM-DDTHH:MM:SS.SSZ

Example JSON Request and Response

The user would submit a request similar to the following example.

GET https://api.manheim.com/events/id/11c00340-6ef8-11e6-adbf-d9658aXXXXXX

The user would receive a similar response for the specific event related to the ID provided in the request.

{
  "href": "https://api.manheim.com/events/id/11c00340-6ef8-11e6-adbf-d9658aXXXXXX",
  "resource": "https://api.manheim.com/units/id/997c8c3c-664b-11e6-bf0f-614176XXXXXX",
  "relatedResources": [
    "https://api.manheim.com/accounts/id/#######",
    "https://api.manheim.com/companies/id/#######"
  ],
  "body": {
    "href": "https://api.manheim.com/units/id/997c8c3c-664b-11e6-bf0f-614176XXXXXX",
    "vin": "XXXXXXXXXXXXXXXXX",
    "type": "PASSENGER_VEHICLE",
    "active": true,
    "updatedOn": "2016-08-19T20:29:16.507Z",
    "createdOn": "2016-08-19T20:29:16.507Z",
    "contact": {
      "customerId": "#######",
      "accountId": "#######",
      "contactName": "John Smith",
      "companyName": "John's Used Cars",
      "phone": "(555) 555-5555",
      "manheimAccountNumber": "#######"
    },
    "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": "400 N Beck Ave",
      "city": "Chandler",
      "state": "AZ",
      "zip": "85226-1700"
    },
    "title": {
      "state": "CA",
      "location": "AT_AUCTION",
      "branding": "Not Specified"
    },
    "customer": {
      "href": "https://api.manheim.com/contacts/id/a54b8c16-0945-45bf-9f62-0a82fdXXXXXX/company"
    },
    "account": {
      "href": "https://api.manheim.com/contacts/id/a54b8c16-0945-45bf-9f62-0a82fdXXXXXX/account"
    },
    "owner": {
      "manheimAccountNumber": "#######",
      "account": {
        "href": "https://api.manheim.com/contacts/id/a54b8c16-0945-45bf-9f62-0a82fdXXXXXX/account"
      },
      "company": {
        "href": "https://api.manheim.com/contacts/id/a54b8c16-0945-45bf-9f62-0a82fdXXXXXX/company"
      }
    }
  },
  "eventType": "NOUN.VERB",
  "createdOn": "2016-08-30T21:24:01.012Z",
  "updatedOn": "2016-08-30T21:24:01.012Z"
}

Retrieve Events by Subscriber

Endpoint

GET /events/subscriber/ID

The ID at the end of the URL should be replaced with the Manheim subscriber ID that the user may obtain through the Subscriptions API.

Description

Allows a user to retrieve all the events they subscribe to during a certain time period based on the subscriber ID of the user

Common Return Codes

Manheim APIs generally returns standard HTTP status codes.

200 OK: A successful response, which includes the requested event(s) in the response
400 Bad Request: ERROR: Request may be malformed; body contains information about the error
401 Unauthorized: ERROR: The authorization may be malformed or the user may not have access; check and resubmit
404 Not Found: ERROR: The request may be malformed; check and resubmit
596: ERROR: The URL or HTTP method may be malformed; check and resubmit

Parameters of JSON Request

The following query parameters are OPTIONAL unless otherwise noted in the URL of the request to Retrieve Events by Subscriber.

Parameter	Type	Requirement	Notes
startTime	String	REQUIRED	Beginning date and time of the requested event(s) collection in UTC format YYYY-MM-DDTHH:MM:SS.SSZ
endTime	String	REQUIRED	Ending date and time of the requested event(s) collection in UTC format YYYY-MM-DDTHH:MM:SS.SSZ
limit	Integer	OPTIONAL	Number indicating the number of event(s) to be returned with a default setting of "25"
pageId	String	OPTIONAL	ID of a certain page of events; obtained from the URL of the next field in the response

Parameters of JSON Response

The response contains the fields listed above for the response to Retrieve an Event by ID in addition to the ones listed in this section. This method has one exception in that eventType is replaced by type in the response.

Field	Notes
href	URL of the request to Retrieve Events by Subscriber
first	URL of the first page of the response
next	URL of the next page of the response, contains the pageId in the URL
items	Contains an array of events related to a subscriber's ID
type	Title of the event

Example JSON Request and Response

The following example shows a request with all of the OPTIONAL and REQUIRED query parameters that a request may have.

https://api.manheim.com/events/subscriber/150dd092-75f9-11e6-baa8-238073XXXXXX?limit=1&startTime=2013-06-08T04:00:00Z&endTime=2017-12-31T04:00:00Z&pageId=16074320-75f9-11e6-bd39-d1f17bXXXXXX

The request to Retrieve Events by Subscriber would return a response similar to the method to Retrieve an Event by ID, with the addition of the fields noted in the previous section, as shown in the example below.

{
  "href": "https://api.manheim.com/events/subscriber/150dd092-75f9-11e6-baa8-238073XXXXXX?limit=1&startTime=2013-06-08T04:00:00Z&endTime=2017-12-31T04:00:00Z",
  "next": "https://api.manheim.com/events/subscriber/150dd092-75f9-11e6-baa8-238073XXXXXX?limit=1&startTime=2013-06-08T04:00:00Z&endTime=2017-12-31T04:00:00Z&pageId=16074320-75f9-11e6-bd39-d1f17bXXXXXX",
  "limit": 1,
  "items": [
    {
      "href": "https://api.manheim.com/events/id/15f5de00-75f9-11e6-bd39-d1f17bXXXXXX",
      "body": {
        "type": "NOUN.NOUN.VERB",
        "status": "UPDATED",
        "href": "https://api.manheim.com/orders/id/hash/a6f2dbe635bc974db8008210a9885c7941XXXXXX",
        "transporter": "Manheim Transportation",
        "unit": {
          "href": "https://api.manheim.com/units/id/f00f7ea0-818c-11e5-a9d8-12f594XXXXXX",
          "type": "PASSENGER_VEHICLE",
          "vin": "XXXXXXXXXXXXXXXXX",
          "operable": true,
          "description": {
            "modelYear": 1995,
            "make": "TOYOTA",
            "model": "CAMRY LE",
            "trim": "GT Convertible 2-Door",
            "interiorColor": {
              "code": "RED",
              "description": "Red"
            },
            "exteriorColor": {
              "code": "WHITE",
              "description": "White"
            },
            "engine": {
              "type": "V8",
              "horsepower": 420,
              "displacement": "5.0L"
            },
            "transmission": "automatic",
            "driveType": "two wheel drive"
          },
          "odometer": {
            "reading": 376,
            "units": "Miles",
            "digits": 8
          },
          "owner": {
            "href": "https://api.manheim.com/companies/id/#######",
            "customerName": "Dealer Auto Sales",
            "alternativeIDs": [
              {
                "type": "XX",
                "value": "#######"
              }
            ]
          },
          "consignment": {
            "href": "https://api.manheim.com/consignments/id/f05352e2-818c-11e5-839f-619503XXXXXX",
            "operatingLocation": {
              "href": "https://api.manheim.com/locations/id/AAA"
            },
            "referenceId": {
              "workOrder": "#######"
            }
          },
          "account": {
            "href": "https://api.manheim.com/accounts/id/#######",
            "customer": {
              "href": "https://api.manheim.com/companies/id/#######"
            }
          }
        },
        "pickupLocation": {
          "name": "Manheim Atlanta",
          "address1": "123 Main ST",
          "address2": "Lot B",
          "city": "Atlanta",
          "stateProvinceCode": "GA",
          "zipcode": "30318",
          "countryCode": "US"
        },
        "pickupContacts": [
          {
            "name": "James Smith",
            "number": "### ### ####"
          }
        ],
        "deliveryLocation": {
          "name": "Dealer Auto Sales",
          "address1": "121 N Main St",
          "city": "Eastman",
          "stateProvinceCode": "WI",
          "zipcode": "54626",
          "countryCode": "US",
          "type": "AUCTION"
        },
        "deliveryContacts": [
          {
            "name": "John Smith",
            "number": "### ### ####"
          }
        ],
        "createdOn": "2014-08-01T10:39:51.000+0000"
      },
      "createdOn": "2016-09-08T19:18:55.712Z",
      "updatedOn": "2016-09-08T19:18:55.712Z",
      "resource": "https://api.manheim.com/orders/id/hash/a6f2dbe635bc974db8008210a9885c7941XXXXXX",
      "relatedResources": [],
      "type": "NOUN.NOUN.VERB"
    }
  ]
}

Retrieve Events by Subscription

Endpoint

GET /events/subscription/ID

Description

Allows a user to retrieve all events related to a specific subscription ID
Users may create a subscription via the Subscriptions API

Common Return Codes

Manheim APIs generally return standard HTTP status codes.

200 OK: A successful response, which includes the requested event(s) in the response
400 Bad Request: ERROR: Request may be missing a required parameter; response contains details about the error
401 Unauthorized: ERROR: The authorization may be malformed or the user may not have access; check and resubmit
404 Not Found: ERROR: Request may be malformed or the subscription ID was invalid; check and resubmit
596: ERROR: Request or URL may be malformed; check and resubmit

Parameters of JSON Request

This method uses the same query parameters as the method to Retrieve Events by Subscriber.

Parameters of JSON Response

The response is similar to the response to Retrieve Events by Subscriber. The parameters for the Retrieve Events by Subscriber method are equivalent to those returned by the Retrieve Events by Subscription method.

Example JSON Request and Response

The following example shows a request to Retrieve Events by Subscription using only the required query parameters.

https://api.manheim.com/events/subscription/f2c4185cf9e8ebf57115ecbadfXXXXXX?startTime=2014-01-31T04:00:00Z&endTime=2016-12-31T04:00:00Z

The response is similar to the Example of JSON Response to Retrieve Events by Subscriber above.

Retrieve Events by Resource

Endpoint

GET /events/resource/resourceId

The "resourceType" and "resourceId" would be replaced by their respective values, as shown in the example below.

Description

Allows a user to search for an event from resource hrefs found in events
Users may use any resource that has an ID related to an event
Users may only view resources to which they have access

Common Return Codes

Manheim APIs generally return standard HTTP status codes.

200 OK: A successful response, which includes the requested event(s) in the response
401 Unauthorized: ERROR: The authorization may be malformed or the user may not have access; check and resubmit
404 Not Found: ERROR: Request may be malformed; check and resubmit
596: ERROR: Request or URL may be malformed; check and resubmit

Parameters of JSON Request

If an href has the form in the example below, it is eligible to be used a "resource" and "resourceId" in the request to Retrieve Events by Resource. An href may include multiple "NOUNS" in the URL.

GET https://api.manheim.com/events/NOUN/ID

GET https://api.manheim.com/events/NOUN/NOUN/ID

The "NOUN" and "ID" would be replaced by valid values, as shown in the example below.

GET https://api.manheim.com/events/units/id/f00f7ea0-818c-11e5-a9d8-12f594XXXXXX

The URLS of this method are nested, so that a user does not need to include the "/id" in their request, as shown in the example below that includes multiple "NOUNS".

GET https://api.manheim.com/events/orders/consignment/fe21da80-7ffe-11e6-b7a8-4583d7XXXXXX

Parameters of JSON Response

The parameters for the Retrieve Events by Resource method are equivalent to those returned by the Retrieve Events by Subscriber method .

Example JSON Request and Response

The below is an example of a request to Retrieve Events by Resource using the above resource example.

GET https://api.manheim.com/events/orders/consignment/fe21da80-7ffe-11e6-b7a8-4583d7XXXXXX

The request example above would produce a similar response to the Escaped JSON example below.

https://api.manheim.com/events/orders/consignment/fe21da80-7ffe-11e6-b7a8-4583d7XXXXXX
{
    "href": "https://api.manheim.com/events/orders/consignment/fe21da80-7ffe-11e6-b7a8-4583d7XXXXXX?limit=25",
    "limit": 25,
    "items": [
        {
            "href": "https://api.manheim.com/events/id/fe440470-7ffe-11e6-9850-b97b26XXXXXX",
            "body": "{\"href\":\"https://api.manheim.com/consignments/id/fe21da80-7ffe-11e6-b7a8-4583d7XXXXXX\",\"unit\":{\"href\...}",
            "createdOn": "2016-09-21T13:26:24.567Z",
            "updatedOn": "2016-09-21T13:26:24.567Z",
            "resource": "https://api.manheim.com/consignments/id/fe21da80-7ffe-11e6-b7a8-4583d7XXXXXX",
            "relatedResources": [],
            "type": "CONSIGNMENTS.CREATED"
        },
        {
            "href": "https://api.manheim.com/events/id/ff03d200-7ffe-11e6-9850-b97b26XXXXXX",
            "body": "{\"href\":\"https://api.manheim.com/consignments/id/fe21da80-7ffe-11e6-b7a8-4583d7XXXXX\",\"unit\":{\"href\...}",
            "createdOn": "2016-09-21T13:26:25.824Z",
            "updatedOn": "2016-09-21T13:26:25.824Z",
            "resource": "https://api.manheim.com/consignments/id/fe21da80-7ffe-11e6-b7a8-4583d7XXXXXX",
            "relatedResources": [],
            "type": "CONSIGNMENTS.UPDATED"
        }
    ]
}

/events ​

Events ​

Events Overview ​

URLs and Environments ​

Create an Event ​

Endpoint ​

Description ​

Common Return Codes ​

Parameters of the JSON Request ​

Example JSON Request and Response ​

Retrieve Events by ID ​

Endpoint ​

Description ​

Common Return Codes ​

Parameters of JSON Response ​

Example JSON Request and Response ​

Retrieve Events by Subscriber ​

Endpoint ​

Description ​

Common Return Codes ​

Parameters of JSON Request ​

Parameters of JSON Response ​

Example JSON Request and Response ​

Retrieve Events by Subscription ​

Endpoint ​

Description ​

Common Return Codes ​

Parameters of JSON Request ​

Parameters of JSON Response ​

Example JSON Request and Response ​

Retrieve Events by Resource ​

Endpoint ​

Description ​

Common Return Codes ​

Parameters of JSON Request ​

Parameters of JSON Response ​

Example JSON Request and Response ​

/events

Events

Events Overview

URLs and Environments

Create an Event

Endpoint

Description

Common Return Codes

Parameters of the JSON Request

Example JSON Request and Response

Retrieve Events by ID

Endpoint

Description

Common Return Codes

Parameters of JSON Response

Example JSON Request and Response

Retrieve Events by Subscriber

Endpoint

Description

Common Return Codes

Parameters of JSON Request

Parameters of JSON Response

Example JSON Request and Response

Retrieve Events by Subscription

Endpoint

Description

Common Return Codes

Parameters of JSON Request

Parameters of JSON Response

Example JSON Request and Response

Retrieve Events by Resource

Endpoint

Description

Common Return Codes

Parameters of JSON Request

Parameters of JSON Response

Example JSON Request and Response