/expand

Standalone Expander

The Standalone Expander API allows consumers to expand the information within an event message. Consumers submit the contents of the message they want expanded along with the field names for the associated resources that they want expanded, and the system returns an expanded version of the event message.

Details for the Expander function are provided below. The event message and the requested expansions are encoded within a single JSON object, details and examples of which are also provided below.

URLs and Environments

The base URL for the Standalone Expander API is /expand. 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.

Expand an Event Message

Endpoint

POST /expand

Common Return Codes

The Expander API generally returns standard HTTP status codes.

• 200 OK: A successful response, which includes a JSON object whose attributes are described below; the contents of the JSON object includes the expanded event message.
• 400 Bad Request: ERROR: the request's JSON object is malformed, or a required property is missing from the request; the response may include details such as which required field is missing.
• 401 Unauthorized: ERROR: the request is made by an unauthorized user, who should contact us at api-support@manheim.com if there are any questions about authorization; the response may include details about the error.

JSON Attributes

In the tables below, capitalized Notes indicate a defined list of accepted values.

If the field is described as an array, then the field can contain any number of values, and each value should be listed in its own entry.

Attributes for a Submission to the Expander API

Field	Type	Notes
body	n/a	The event message to be expanded; the contents can be found in the body attribute of the original event message
expansions	n/a	An array listing the attributes within the body that should be expanded; the array can include the attribute root to expand the top-level href attribute for the contents of the body attribute; see the NOTES below

NOTES:

• The system processes expansions by inserting the results of a GET called against a node-level HREF property, so elements without that property will NOT be expanded, including array elements in the event message.
• The expansions array can include the keyword root to expand the top-level href attribute for the contents of the body attribute.
• If the expansions array includes an element that is not found in the body attribute, the system will attempt to locate the element by expanding the element's parent node and subsequent ancestors up to the top-level root node.

For example, suppose units.consignments is included in the expansions array but missing from the body attribute.

• If units is included in the message body, the system will expand the the object to try to find units.consignments.
• Otherwise, the system will expand the top-level root object to find units and then expand units to find units.consignments.

Attributes for a Successful Expander Response

NOTE: The JSON object that is returned by the API does not have a set format: its format resembles the contents of the body attribute in the JSON request object, the difference being that each of the attributes within the submitted expansions array is replaced with the full contents of that associated resource.

Attributes for Error Messages within an Expander Response

NOTE: If a response from the Expander API includes error messages, the messages will be placed in an array in or near the attribute which prompted the error; the array is described below.

Field	Notes
expansion_errors	An array of errors, where each entry has a property, message, and developerMessage attribute

JSON Examples: API Objects

Originating Event Message, EventType of TITLES.VALIDATED

The following is an example of an event message that could be expanded through the Expander API: the contents of the message's body attribute would be submitted in the body attribute of the JSON object submitted to the /expand endpoint, as shown further below.

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

{
    "href": "https://uat.api.manheim.com/events/id/dfba84a0-922b-11e5-b4b8-7f191bdfdc56",
    "eventType": "TITLES.VALIDATED",
    "body": {
        "unit": {
            "href": "https://uat.api.manheim.com/units/id/78279590-922a-11e5-ac0d-12276485ab15"
        },
        "status": "VALIDATED",
        "operatingLocation": {
            "href": "https://uat.api.manheim.com/locations/id/PSM1"
        },
        "vin": "1FTFW1EF0BKD40798",
        "href": "https://uat.api.manheim.com/titles/id/3506787f-8e99-4162-be0e-9b91e12d47c1"
    },
    "createdOn": "2015-11-23T21:48:03.946Z",
    "subscription": {
        "href": "https://uat.api.manheim.com/subscriptions/id/2bf4cfd0f9abbf7cd314bd651f3365f8"
    },
    "subscriber": {
        "href": "https://uat.api.manheim.com/subscribers/id/2ab40a60-798d-11e5-8c89-75e884a7e362"
    }
}

Submitted to Expand an Event Message

The following is what could be submitted to expand the example TITLES.VALIDATED event message documented above.

As instructed by the array of values in the expansions attribute, the system will expand the top-level "root" href attribute, which points to the title that had just been validated.

The API will also expand the unit.consignments resource. Since that resource is not included in the body attribute, the system will expand the unit resource to find its consignments resource, and then expand consignments.

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

{
    "expansions": [
        "root",
        "unit.consignments"
    ],
    "body": {
        "unit": {
            "href": "https://uat.api.manheim.com/units/id/78279590-922a-11e5-ac0d-12276485ab15"
        },
        "status": "VALIDATED",
        "operatingLocation": {
            "href": "https://uat.api.manheim.com/locations/id/PSM1"
        },
        "vin": "1FTFW1EF0BKD40798",
        "href": "https://uat.api.manheim.com/titles/id/3506787f-8e99-4162-be0e-9b91e12d47c1"
    }
}

Returned by Expand an Event Message, Successful Execution

The following example contains the same message that was submitted in the example above, with expanded information for the top-level "root" href containing the validated title, the unit attribute which was expanded to find its consignments attribute, and the unit.consignments attribute itself.

{
    "unit": {
        "href": "https://uat.api.manheim.com/units/id/78279590-922a-11e5-ac0d-12276485ab15",
        "customer": {
            "href": "https://uat.api.manheim.com/companies/id/293538"
        },
        "type": "UNKNOWN",
        "contact": {
            "customerId": "293538",
            "accountId": "455311",
            "manheimAccountNumber": "5107309"
        },
        "title": {
            "operatingLocation": {
                "href": "https://uat.api.manheim.com/locations/id/PMM1"
            },
            "href": "https://uat.api.manheim.com/titles/id/3506787f-8e99-4162-be0e-9b91e12d47c1"
        },
        "description": {
            "model": "F-150",
            "engine": {
                "displacement": 5,
                "fuel": "Flex Fuel Capability",
                "type": "8 Cylinder Engine"
            },
            "modelYear": 2011,
            "doorCount": 0,
            "trim": "FX4",
            "transmission": "6-Speed A/T",
            "make": "Ford"
        },
        "vin": "1FTFW1EF0BKD40798",
        "updatedOn": "2015-11-23T21:38:00.684Z",
        "offerings": {
            "href": "https://uat.api.manheim.com/offerings/unit/78279590-922a-11e5-ac0d-12276485ab15"
        },
        "subscriptions": {
            "href": "https://uat.api.manheim.com/subscriptions/unit/78279590-922a-11e5-ac0d-12276485ab15"
        },
        "consignments": {
            "href": "https://uat.api.manheim.com/consignments/unit/78279590-922a-11e5-ac0d-12276485ab15",
            "items": [
                {
                    "href": "https://uat.api.manheim.com/consignments/id/786a7752-922a-11e5-b527-37161de37ada",
                    "unit": {
                        "href": "https://uat.api.manheim.com/units/id/78279590-922a-11e5-ac0d-12276485ab15"
                    },
                    "checkInDate": "2015-11-23",
                    "status": "CHECKED_IN",
                    "operatingLocation": {
                        "href": "https://uat.api.manheim.com/locations/id/PMM1"
                    },
                    "customerId": "293538",
                    "updatedOn": "2015-11-23T21:38:02.215Z",
                    "createdOn": "2015-11-23T21:38:01.131Z",
                    "referenceId": {
                        "workOrderNumber": "2350504"
                    },
                    "orders": {
                        "href": "https://uat.api.manheim.com/orders/consignment/786a7752-922a-11e5-b527-37161de37ada"
                    },
                    "offerings": {
                        "href": "https://uat.api.manheim.com/offerings/consignment/786a7752-922a-11e5-b527-37161de37ada"
                    },
                    "notes": {
                        "href": "https://uat.api.manheim.com/notes/consignment/786a7752-922a-11e5-b527-37161de37ada"
                    }
                }
            ]
        },
        "odometer": {
            "reading": 9900,
            "digits": 0,
            "type": "DIGITAL",
            "units": "MILES"
        },
        "createdOn": "2015-11-23T21:38:00.684Z",
        "account": {
            "href": "https://uat.api.manheim.com/accounts/id/455311"
        },
        "active": true,
        "orders": {
            "href": "https://uat.api.manheim.com/orders/unit/78279590-922a-11e5-ac0d-12276485ab15"
        },
        "notes": {
            "href": "https://uat.api.manheim.com/notes/unit/78279590-922a-11e5-ac0d-12276485ab15"
        }
    },
    "status": "VALIDATED",
    "operatingLocation": {
        "href": "https://uat.api.manheim.com/locations/id/PSM1"
    },
    "vin": "1FTFW1EF0BKD40798",
    "href": "https://uat.api.manheim.com/titles/id/3506787f-8e99-4162-be0e-9b91e12d47c1",
    "stateProvinceCode": "IN",
    "number": null,
    "bodyStyle": null,
    "releasedTo": "BUYER",
    "color": null,
    "make": "Ford",
    "model": "F-150",
    "odometer": {
        "reading": 9900,
        "units": "miles"
    },
    "year": 2011,
    "image": "https://uat.api.manheim.com/titles/image/22e9352f-0818-4618-ba7e-023ebfe72c5f",
    "shippingInformation": {
        "location": {
            "href": "https://api.manheim.com/locations/id/NOAA",
            "locationName": "ROBERT E WELLS ENTERPRISES INC",
            "address": {
                "address1": "8102 Collingwood Lane",
                "address2": "Suite 6001",
                "city": "Alpharetta",
                "stateProvinceRegion": "GA",
                "postalCode": 30038,
                "country": "US"
            },
            "contactPhone": "(281) 530-1800",
            "contactName": "WELLS, ROBERT"
        },
        "shippedOn": null,
        "carrier": null,
        "trackingNumber": null
    },
    "titleNotRequired": false,
    "brandings": {
        "href": "https://uat.api.manheim.com/titles/id/3506787f-8e99-4162-be0e-9b91e12d47c1?tag=BRANDINGS",
        "items": []
    },
    "exceptions": {
        "href": "https://uat.api.manheim.com/titles/id/3506787f-8e99-4162-be0e-9b91e12d47c1?tag=EXCEPTIONS",
        "items": []
    },
    "announcements": {
        "href": "https://uat.api.manheim.com/titles/id/3506787f-8e99-4162-be0e-9b91e12d47c1?tag=ANNOUNCEMENTS",
        "items": []
    },
    "updatedOn": "2015-11-23T21:52:14.618+0000",
    "receivedOn": "2015-11-06T18:57:45.208+0000",
    "validatedOn": "2015-11-23T21:48:01.289+0000",
    "matchedOn": "2015-11-23T21:38:22.971+0000",
    "exceptedOn": null
}

Submitted to Expand an Event Message, Including a Bad Expansion Request

The following matches the example above, but the expansions array includes the attribute unit.consigments.items, which is an array and does not have an href value at its top level.

The submitted request will generate an expansion error, as shown further below.

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

{
    "expansions": [
        "root",
        "unit.consignments",
        "unit.consignments.items"
    ],
    "body": {
        "unit": {
            "href": "https://uat.api.manheim.com/units/id/78279590-922a-11e5-ac0d-12276485ab15"
        },
        "status": "VALIDATED",
        "operatingLocation": {
            "href": "https://uat.api.manheim.com/locations/id/PSM1"
        },
        "vin": "1FTFW1EF0BKD40798",
        "href": "https://uat.api.manheim.com/titles/id/3506787f-8e99-4162-be0e-9b91e12d47c1"
    }
}

Returned by Expand an Event Message, with an Error from a Bad Expansion Request

The JSON example submitted above improperly included an array unit.consignments.items, and as a result, the response includes an expansion_errors object after the items object, at the end of the unit.consignments object.

{
    "unit": {
        "href": "https://uat.api.manheim.com/units/id/78279590-922a-11e5-ac0d-12276485ab15",
        "customer": {
            "href": "https://uat.api.manheim.com/companies/id/293538"
        },
        "type": "UNKNOWN",
        "contact": {
            "customerId": "293538",
            "accountId": "455311",
            "manheimAccountNumber": "5107309"
        },
        "title": {
            "operatingLocation": {
                "href": "https://uat.api.manheim.com/locations/id/PMM1"
            },
            "href": "https://uat.api.manheim.com/titles/id/3506787f-8e99-4162-be0e-9b91e12d47c1"
        },
        "description": {
            "model": "F-150",
            "engine": {
                "displacement": 5,
                "fuel": "Flex Fuel Capability",
                "type": "8 Cylinder Engine"
            },
            "modelYear": 2011,
            "doorCount": 0,
            "trim": "FX4",
            "transmission": "6-Speed A/T",
            "make": "Ford"
        },
        "vin": "1FTFW1EF0BKD40798",
        "updatedOn": "2015-11-23T21:38:00.684Z",
        "offerings": {
            "href": "https://uat.api.manheim.com/offerings/unit/78279590-922a-11e5-ac0d-12276485ab15"
        },
        "subscriptions": {
            "href": "https://uat.api.manheim.com/subscriptions/unit/78279590-922a-11e5-ac0d-12276485ab15"
        },
        "consignments": {
            "href": "https://uat.api.manheim.com/consignments/unit/78279590-922a-11e5-ac0d-12276485ab15",
            "items": [
                {
                    "href": "https://uat.api.manheim.com/consignments/id/786a7752-922a-11e5-b527-37161de37ada",
                    "unit": {
                        "href": "https://uat.api.manheim.com/units/id/78279590-922a-11e5-ac0d-12276485ab15"
                    },
                    "checkInDate": "2015-11-23",
                    "status": "CHECKED_IN",
                    "operatingLocation": {
                        "href": "https://uat.api.manheim.com/locations/id/PMM1"
                    },
                    "customerId": "293538",
                    "updatedOn": "2015-11-23T21:38:02.215Z",
                    "createdOn": "2015-11-23T21:38:01.131Z",
                    "referenceId": {
                        "workOrderNumber": "2350504"
                    },
                    "orders": {
                        "href": "https://uat.api.manheim.com/orders/consignment/786a7752-922a-11e5-b527-37161de37ada"
                    },
                    "offerings": {
                        "href": "https://uat.api.manheim.com/offerings/consignment/786a7752-922a-11e5-b527-37161de37ada"
                    },
                    "notes": {
                        "href": "https://uat.api.manheim.com/notes/consignment/786a7752-922a-11e5-b527-37161de37ada"
                    }
                }
            ],
            "expansion_errors": [
                {
                    "field": "items",
                    "message": "Cannot expand an array",
                    "developerMessage": "Cannot expand an array"
                }
            ]
        },
        "odometer": {
            "reading": 9900,
            "digits": 0,
            "type": "DIGITAL",
            "units": "MILES"
        },
        "createdOn": "2015-11-23T21:38:00.684Z",
        "account": {
            "href": "https://uat.api.manheim.com/accounts/id/455311"
        },
        "active": true,
        "orders": {
            "href": "https://uat.api.manheim.com/orders/unit/78279590-922a-11e5-ac0d-12276485ab15"
        },
        "notes": {
            "href": "https://uat.api.manheim.com/notes/unit/78279590-922a-11e5-ac0d-12276485ab15"
        }
    },
    "status": "VALIDATED",
    "operatingLocation": {
        "href": "https://uat.api.manheim.com/locations/id/PSM1"
    },
    "vin": "1FTFW1EF0BKD40798",
    "href": "https://uat.api.manheim.com/titles/id/3506787f-8e99-4162-be0e-9b91e12d47c1",
    "stateProvinceCode": "IN",
    "number": null,
    "bodyStyle": null,
    "releasedTo": "BUYER",
    "color": null,
    "make": "Ford",
    "model": "F-150",
    "odometer": {
        "reading": 9900,
        "units": "miles"
    },
    "year": 2011,
    "image": "https://uat.api.manheim.com/titles/image/ed641d51-a0e2-43a4-8827-7825f4249ec7",
    "shippingInformation": {
        "location": {
            "href": "https://api.manheim.com/locations/id/NOAA",
            "locationName": "ROBERT E WELLS ENTERPRISES INC",
            "address": {
                "address1": "8102 Collingwood Lane",
                "address2": "Suite 6001",
                "city": "Alpharetta",
                "stateProvinceRegion": "GA",
                "postalCode": 30038,
                "country": "US"
            },
            "contactPhone": "(281) 530-1800",
            "contactName": "WELLS, ROBERT"
        },
        "shippedOn": null,
        "carrier": null,
        "trackingNumber": null
    },
    "titleNotRequired": false,
    "brandings": {
        "href": "https://uat.api.manheim.com/titles/id/3506787f-8e99-4162-be0e-9b91e12d47c1?tag=BRANDINGS",
        "items": []
    },
    "exceptions": {
        "href": "https://uat.api.manheim.com/titles/id/3506787f-8e99-4162-be0e-9b91e12d47c1?tag=EXCEPTIONS",
        "items": []
    },
    "announcements": {
        "href": "https://uat.api.manheim.com/titles/id/3506787f-8e99-4162-be0e-9b91e12d47c1?tag=ANNOUNCEMENTS",
        "items": []
    },
    "updatedOn": "2015-11-23T21:52:14.618+0000",
    "receivedOn": "2015-11-06T18:57:45.208+0000",
    "validatedOn": "2015-11-23T21:48:01.289+0000",
    "matchedOn": "2015-11-23T21:38:22.971+0000",
    "exceptedOn": null
}

Returned by Expand an Event Message, with a 404 Error

The following JSON example is from a proper request, but in attempting to expand the unit attribute, the system discovers that the object in question is not found.

The response includes an expansion_errors object at the end of the unit object.

{
    "unit": {
        "href": "https://uat.api.manheim.com/units/id/78279590-922a-11e5-ac0d-12276485ab99",
        "expansion_errors": [
            {
                "property": "href",
                "message": "resource not found",
                "developerMessage": "resource href returned 404",
                "correlation_id": "d116ad16-06a4-4fdf-a029-efc89c3c7ca8"
            }
        ]
    },
    "status": "VALIDATED",
    "operatingLocation": {
        "href": "https://uat.api.manheim.com/locations/id/PSM1"
    },
    "vin": "1FTFW1EF0BKD40798",
    "href": "https://uat.api.manheim.com/titles/id/3506787f-8e99-4162-be0e-9b91e12d47c1",
    "stateProvinceCode": "IN",
    "number": null,
    "bodyStyle": null,
    "releasedTo": "BUYER",
    "color": null,
    "make": "Ford",
    "model": "F-150",
    "odometer": {
        "reading": 9900,
        "units": "miles"
    },
    "year": 2011,
    "image": "https://uat.api.manheim.com/titles/image/2b3221b3-73a4-48c3-90df-fb299e0b0734",
    "shippingInformation": {
        "location": {
            "href": "https://api.manheim.com/locations/id/NOAA",
            "locationName": "ROBERT E WELLS ENTERPRISES INC",
            "address": {
                "address1": "8102 Collingwood Lane",
                "address2": "Suite 6001",
                "city": "Alpharetta",
                "stateProvinceRegion": "GA",
                "postalCode": 30038,
                "country": "US"
            },
            "contactPhone": "(281) 530-1800",
            "contactName": "WELLS, ROBERT"
        },
        "shippedOn": null,
        "carrier": null,
        "trackingNumber": null
    },
    "titleNotRequired": false,
    "brandings": {
        "href": "https://uat.api.manheim.com/titles/id/3506787f-8e99-4162-be0e-9b91e12d47c1?tag=BRANDINGS",
        "items": []
    },
    "exceptions": {
        "href": "https://uat.api.manheim.com/titles/id/3506787f-8e99-4162-be0e-9b91e12d47c1?tag=EXCEPTIONS",
        "items": []
    },
    "announcements": {
        "href": "https://uat.api.manheim.com/titles/id/3506787f-8e99-4162-be0e-9b91e12d47c1?tag=ANNOUNCEMENTS",
        "items": []
    },
    "updatedOn": "2015-11-23T21:52:14.618+0000",
    "receivedOn": "2015-11-06T18:57:45.208+0000",
    "validatedOn": "2015-11-23T21:48:01.289+0000",
    "matchedOn": "2015-11-23T21:38:22.971+0000",
    "exceptedOn": null
}