API Developer Portal

Appearance

/subscriptions ​

Subscriptions ​

Overview ​

The Subscriptions API is used by customers to provide filter criteria to receive events on the customer's callback. The Subscription endpoints allow customers to create and manage their subscriptions.

A Subscription defines filter criteria based on underlying business needs to receive a particular set of events. For example, when a subscription has criteria such as company id -ABC & event type - unit.created, the Customer will receive only those events that are of type unit.created & where the unit belongs to the company ABC.

A valid, existing Subscriber ID is required to create a Subscription.

NOTE: External customers sending requests to this API with the client_credentials grant type must use an access token obtained from the current token endpoint (https://api.manheim.com/oauth2/token). This applies to all API methods for creating, updating, retrieving, or deleting subscriptions.

URLs and Environments ​

The base URL for the Subscriptions API is /subscriptions. 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 a Subscription for customer with External scope- Overview ​

Endpoint ​

POST /subscriptions

Description ​

Use this endpoint to create a subscription to Manheim events based on filter criteria that specifies a resource, an event type, or a VIN entered as text. You can also use a richFilter to define more detailed filter criteria based on resource, type, or text (VIN). Each option is explained in the subsequent sections.

Common Return Codes ​

Response CodeDescriptionPossible Next Actions
201 CreatedSuccessful responseNo action necessary
400 Bad RequestRequired parameter missing or parameter data type incorrect; response body describes errorMake the necessary corrections and re-submit the request
401 UnauthorizedAccess denied due to incorrect credentials, malformed API token, or because user does not have accessValidate the token or contact us for API access
404 Not FoundData specified in the request was not foundModify request and resubmit
415 Unsupported Media TypeMessage contains details about what content type is not supportedRequest must be in JSON format; confirm that Content-Type header is set as application/json; reformat and resubmit
503 Service UnavailableThe application server rejected the connection or there is a SQL exceptionEnsure that the request is valid and resubmit. If the problem persists, contact your Manheim support representative

NOTES

  • 201 Created: A successful response that the new subscription is created. The response includes a location "href" URL with the system-generated subscription ID.
  • 400 Bad Request: ERROR:. The JSON request is malformed & subscription is not created.

Request Parameters ​

FieldTypeRequirementDescription
subscriberObjectREQUIREDSubscriber id url for subscription. The URL must use the secure HTTPS protocol
subscriber.hrefStringREQUIREDURL representing the subscriber for this subscription, created with the /subscribers API.
criteriaArrayREQUIREDContains one or more objects, each specifying resource and/or type and/or text filter criteria
criteria.resourceStringREQUIRED for subscription based on resource, type, or text criteriaURL that uniquely identifies a particular resource. Company ID URL is required while creating subscription by Type or Text. Other resource urls can be added per need (details below)
criteria.typeStringRequired if using richFilter with type criteriaAn event type matching an auction business scenario, for example UNIT.CREATED.
criteria.textStringREQUIRED if using richFilter with text criteriaVIN for a specific vehicle
criteria.richFilterStringOPTIONALSpecifies more details for resource-, type-, or text-based subscription; supplies parameter(s) found in event body, such as "body.status=='SOLD'"

Create a Subscription by Resource ​

Endpoint ​

POST /subscriptions

Description ​

Use this endpoint to create a subscription to Manheim events related to a resource, such as events for a particular auction location.

Common Return Codes ​

Response CodeDescriptionPossible Next Actions
201 CreatedSuccessful responseNo action necessary
400 Bad RequestRequired parameter missing or parameter data type incorrect; response body describes errorMake the necessary corrections and re-submit the request
401 UnauthorizedAccess denied due to incorrect credentials, malformed API token, or because user does not have accessValidate the token or contact us for API access
404 Not FoundData specified in the request was not foundModify request and resubmit
415 Unsupported Media TypeMessage contains details about what content type is not supportedRequest must be in JSON format; confirm that Content-Type header is set as application/json; reformat and resubmit
503 Service UnavailableThe application server rejected the connection or there is a SQL exceptionEnsure that the request is valid and resubmit. If the problem persists, contact your Manheim support representative

Request Parameters ​

FieldTypeRequirementDescription
subscriberObjectREQUIREDSubscriber id url for subscription. The URL must use the secure HTTPS protocol
subscriber.hrefStringREQUIREDURL representing the subscriber for this subscription, created with the /subscribers API.
criteriaArrayREQUIREDContains one or more objects, each specifying resource and/or type and/or text filter criteria
criteria.resourceStringREQUIRED for subscription based on resource, type, or text criteriaURL that uniquely identifies a particular resource.

Description of the fields required for subscription ​

  • subscriber: The subscriber id received on successful creation of subscriber. For Example : https://integration1.api.manheim.com/subscribers/id/7952f37e-fa80-11e5-ba93-59b72c8d8d90

  • criteria : The logical filter (based on underlying business need) that define the events received on callback.

    • Criteria as resource :

      • When a customer wants to receive event notifications for a particular resource url.
        • For example, if customer wants to receive all auction related events for a particular location (auction ABC): The location href must be specified as resource criteria.
      • Resource url needs to be SSL certified (provided as https) and a valid Manheim url.
        • Example for resource url:
https://api.manheim.com/units/id/a0d99f10-7e9d-11e5-a6b3-0e836c0111
https://api.manheim.com/companies/id/12343
  • For this type of filter , customer receives events that contain the particular resource url in the event body & thus have a successful filter match.
    • For example: If the event does not have a customer url with the specific customer id as provided in the subscription- there is no match and event is not published to the callback.
  • There can be multiple resource url in a given subscription. The events retrieved would need to have all the resource urls as part of event body for successful match.
  • This criteria does not support anything other than the https url format.

Example for creating subscription by resource ​

POST https://api.manheim.com/subscriptions
{
  "subscriber": {
    "href": "https://api.manheim.com/subscribers/id/a3a331c0-2579-11e5-bf3e-51ae32d34324"
  },
  "criteria": [{
    "resource": {
      "href": "https://api.manheim.com/units/id/a20432432-321-3243124"
    }
  }]
}

Create a Subscription by Type ​

Description ​

Use this method to receive event notifications for a particular business scenario executed through sale channels (auction/other paths).

  • Only one event type per subscription can be mentioned as filter criteria.
    • For example, notify customer whenever vehicles checks into the auction ABC.
- Subscription by type means providing event type( term for an auction business scenario) as a filter. 
  - For example OFFERINGS.CREATED, UNIT.CREATED. 
- A Company id url must be provided as a resource criteria.
- In case of multiple company ids, subscriber would need to be created for each company id. Customer then creates subscriptions related to each subscribers.
- Customer receives event result set for a given event type that belongs to their particular company (resource url- company id).
  - For example:  Subscription for type: UNIT.CREATED & resource - company url with id ABC will provide event result set specific to UNIT.CREATED events that are initiated for company ABC.
- Customer can put **wild card** for type criteria - the event result set will contain all events that match the parent filter. This helps as multiple subscriptions are not required with a wild card.
  - For example: OFFERINGS.\* as type criteria. Customer will receive all events for Offerings - OFFERINGS.CREATED, OFFERINGS.UPDATED, OFFERINGS.CANCELLED.
  For example : ORDERS.TRANSPORTATION.\*. Customer will receive all events for ORDERS.TRANSPORTATION as ORDERS.TRANSPORTATION.CREATED, ORDERS.TRANSPORTATION.UPDATED.

Request Parameters ​

FieldTypeRequirementDescription
subscriberObjectREQUIREDSubscriber id url for subscription. The URL must use the secure HTTPS protocol
subscriber.hrefStringREQUIREDURL representing the subscriber for this subscription, created with the /subscribers API.
criteriaArrayREQUIREDContains one or more objects, each specifying resource and/or type and/or text filter criteria
criteria.resourceStringREQUIRED for subscription based on resource, type, or text criteriaURL that uniquely identifies a particular resource. Company ID URL is required while creating subscription by Type or Text. Other resource urls can be added per need (details below)
criteria.typeStringRequired if using richFilter with type criteriaAn event type matching an auction business scenario, for example UNIT.CREATED.

Example for creating subscription by type ​

POST https://api.manheim.com/subscriptions
{
    "subscriber": {
        "href": "https://api.manheim.com/subscribers/id/a3a331c0-2579-11e5-bf3e-51a3ec34r43r7"
    },
    "criteria": [
        {
            "type": {
                "pattern": "ORDERS.TRANSPORTATION.CREATED"
            }
        },
        {
            "resource": {
                "href": "https://api.manheim.com/companies/id/ABC"
            }
        }
     ]
}

Example for creating subscription by type with wildcard ​

POST https://api.manheim.com/subscriptions
{
    "subscriber": {
        "href": "https://e2e.api.manheim.com/subscribers/id/a3a331c0-2579-11e5-bf3e-51a3ec34b787"
    },
    "criteria": [
        {
            "type": {
                "pattern": "ORDERS.TRANSPORTATION.*"
            }
        },
        {
            "resource": {
                "href": "https://api.manheim.com/companies/id/ABC"
            }
        }
    ]
}

Create a Subscription by Text (VIN) ​

Description ​

Use this method to receive event notifications for a particular vehicle (with given VIN) that goes through the auction business process.

  • This criteria takes VIN as input.
  • It is mandatory to provide resource criteria as company id url for this subscription type, process won't work otherwise.
  • Customers receives events that contain the particular VIN & company id url & match on these with subscription.
  • There can be only one text filter per subscription. Each subscription for text must be dedicated to one single VIN.
  • Text criteria & Resource as company id url can be combined with multiple resource criteria for a more narrowed down event result set.

Request Parameters ​

FieldTypeRequirementDescription
subscriberObjectREQUIREDSubscriber id url for subscription. The URL must use the secure HTTPS protocol
subscriber.hrefStringREQUIREDURL representing the subscriber for this subscription, created with the /subscribers API.
criteriaArrayREQUIREDContains one or more objects, each specifying resource and/or type and/or text filter criteria
criteria.resourceStringREQUIRED for subscription based on resource, type, or text criteriaURL that uniquely identifies a particular resource. Company ID URL is required while creating subscription by Type or Text. Other resource urls can be added per need (details below)
criteria.textStringREQUIRED if using richFilter with text criteriaVIN for a specific vehicle

Example for creating subscription by text ​

POST https://api.manheim.com/subscriptions
{
    "subscriber": {
        "href": "https://api.manheim.com/subscribers/id/a3a331c0-2579-11e5-bf3e-51a3e458485"
    },
    "criteria": [
        {
            "text": "2GNALPEC2BC63DED8"
        },
        {
            "resource": {
                "href": "https://api.manheim.com/company/id/123343"
            }
        }
    ]
}

Create a Subscription with RichFilter Criteria ​

The richFilter subscription criteria allows to filter events in sync with business needs. Client can provide filter query with parameters & logical operators in alignment with business scenario resulting in event set that is optimized & narrowed to the request.

  • Client earlier had limited options to create filter by Type,Text or resource, the richFilter gives an opportunity to further refine the subscription filter.
  • richFilter subscription criteria is a JMES Path Search query string that allows subscribers to do event to subscription match.
  • Subscriber should know the event structure when using Rich-Filter.
  • At-least one Primary Criteria- Resource, Type or Text required to add rich Filter criteria. When creating a subscription, Rich Filter always follows Primary Criteria.
  • Each parameter mentioned in the richFilter query is matched individually with what is in the event body. Events are published to subscriber when all the criteria match.
  • The Company href or Manheim account numbers associated with client's token are automatically added to the subscription criteria.
    • Subscription will only match events that contain the the added company href or one of the Manheim Account Numbers.

Request Parameters ​

FieldTypeRequirementDescription
subscriberObjectREQUIREDSubscriber id url for subscription. The URL must use the secure HTTPS protocol
subscriber.hrefStringREQUIREDURL representing the subscriber for this subscription, created with the /subscribers API.
criteriaArrayREQUIREDContains one or more objects, each specifying resource and/or type and/or text filter criteria
criteria.resourceStringREQUIRED for subscription based on resource, type, or text criteriaURL that uniquely identifies a particular resource. Company ID URL is required while creating subscription by Type or Text. Other resource urls can be added per need (details below)
criteria.typeStringRequired if using richFilter with type criteriaAn event type matching an auction business scenario, for example UNIT.CREATED.
criteria.textStringREQUIRED if using richFilter with text criteriaVIN for a specific vehicle
criteria.richFilterStringOPTIONALSpecifies more details for resource-, type-, or text-based subscription; supplies parameter(s) found in event body, such as "body.status=='SOLD'"

Example of Subscription with Rich Filter ​

1_Existing Subscriber(Please go to Subscriber tab to find details about creating subscriber): https://integration1.api.manheim.com/subscribers/id/1b76f3de-0aac-11e8-8765-2d7426abad32

2_Subscription posted to /subscriptions endpoint:

{
    "subscriber": {
        "href": "https://api.manheim.com/subscribers/id/1b76f3de-0aac-11e8-8765-2d742VVVbad32"
    },
    "criteria": [
        {"type": {"pattern": "OFFERINGS.PURCHASED"}},
        
           {"richFilter": "body.status == 'SOLD'"}

    ]
}

3_A GET on Subscription to see its data (Company ID or Manheim Account Numbers is automatically added to subscription):

  {
      "href":  "https://api.manheim.com/subscriptions/id/b241a149e7c5a542bbe264a8bd969617",
      "subscriber": {
        "href": "https://api.manheim.com/subscribers/id/1b76f3de-0aac-11e8-8765-2d742VVVbad32"
      },
      "criteria": [
        "https://api.manheim.com/companies/id/359443",
        "OFFERINGS.PURCHASED",
        "status == 'SOLD'"
      ],
      "createdOn": "2018-05-01T19:00:23.019Z",
      "updatedOn": "2018-05-01T19:00:23.028Z"
    }

All events received on the callback url is of Type: Offerings.Purchased with status:SOLD & associated with the particular company id href automatically added to the subscription.

href\":\"https://integration1.api.manheim.com/events/id/779aefb0-0aae-11e8-8054-4d492ba5fbe5\",\"eventType\":\"OFFERINGS.PURCHASED\",\"body\":{\"href\":\"https://integration1.api.manheim.com/offerings/in-lane/id/6696d756-0aae-11e8-adf9-4b6c61a8ee22\",\"status\":\"SOLD\",\"unit\":{\"href\":\"https://integration1.api.manheim.com/units/id/6515e93a-0aae-11e8-a71d-49997c79cf01\",\"vin\":\"1C3CDFCB0DD352522\",\"account\":{\"href\":\"https://integration1.api.manheim.com/contacts/id/2ca3b909-92f3-4c80-88b4-e1bb213a4c20/account\",\"customer\":{\"href\":\"https://integration1.api.manheim.com/contacts/id/2ca3b909-92f3-4c80-88b4-e1bb213a4c20/company\"}}},\"purchasePrice\":21733,\"buyerAccount\":{\"account\":{\"href\":\"https://integration1.api.manheim.com/contacts/id/1e66d373-fef9-4b03-a857-6684dc7ae217/account\",\"customer\":{\"href\":\"https://integration1.api.manheim.com/contacts/id/1e66d373-fef9-4b03-a857-6684dc7ae217/company\"}}},\"consignment\":{\"href\":\"https://integration1.api.manheim.com/consignments/id/6560e8cc-0aae-11e8-ad8c-770b01b80072\",\"operatingLocation\":{\"href\":\"https://integration1.api.manheim.com/locations/id/QLM1\"}},\"purchaseDate\":\"2018-02-05T14:55:01.000Z\"},\"createdOn\":\"2018-02-05T19:55:08.203Z\",\"subscription\":{\"href\":\"https://integration1.api.manheim.com/subscriptions/id/764ec0ee7cbade207d5b550498d42041\"},\"subscriber\":{\"href\":\"https://integration1.api.manheim.com/subscribers/id/1b76f3de-0aac-11e8-8765-2d7426abad32\"}}","headers":"{\"HOST\":\"throwitatthewall-prod.elasticbeanstalk.com\",\"X_REAL_IP\":\"10.142.205.122\",\"X_FORWARDED_FOR\":\"52.4.206.249, 10.142.205.122\",\"ACCEPT\":\"*/*\",\"ACCEPT_ENCODING\":\"gzip, deflate\",\"USER_AGENT\":\"rest-client/2.0.2 (linux-gnu x86_64)

How to use Rich Filter criteria ​

  • the Subscriber creates subscription with mandatory Primary Criteria- Type or Resource or Text followed by Rich Filter.
  • All the parameters added to the query need to be represented as the exact qualifier path as present in the source event.
  • The query string parameters start with "body." followed by the field name. When the qualifier path for the field is structured the same as that in the event, there is subscription to event match & event is delivered to the callback.
  • A company id href or Manheim Account Numbers associated with Client's token are automatically added as resource to the subscription.

Business case- Require Notification when VIN - WVWC919XXXXX is sold on OVE channel. 1.RichFilter query string parameters will start with "body" & follow the exact qualifier path as that mentioned in event body. 2.Client requires Offerings.Purchased events for the "old" notifications. 3.Note- Fields of interest are highlighted below:

Event Structure : OFFERINGS.PURCHASED

"body":{"href":"https://integration1.api.manheim.com/events/id/6c1e2740-1000-11e8-8a54-XXXXXXX","eventType":"OFFERINGS.PURCHASED","body":{"href":"https://integration1.api.manheim.com/offerings/ove/id/5b44c6b8-1000-11e8-b659-XXXXXX","channel":"OVE","status":"SOLD","unit":{"href":"https://integration1.api.manheim.com/units/id/5af1ae24-1000-11e8-823c-4ddcd8f8bd05","vin":"WVWC919XXXXX","account":{"href":"https://integration1.api.manheim.com/contacts/id/51f085b3-128b-40ee-872a-d1df16e2c202/account","customer":{"href":"https://integration1.api.manheim.com/contacts/id/51f085b3-128b-40ee-872a-d1df16e2c202/company"}}},"purchasePrice":6000,"buyerAccount":{"account":{"href":"https://integration1.api.manheim.com/contacts/id/1f0ad2ab-6fdd-4fdd-ad10-554e7e86baf0/account","customer":{"href":"https://integration1.api.manheim.com/contacts/id/1f0ad2ab-6fdd-4fdd-ad10-554e7e86baf0/company"}}},"facilitatingLocation":{"href":"https://integration1.api.manheim.com/locations/id/QLM1"},"purchaseDate":"2018-02-12T14:23:41+00:00"},"createdOn":"2018-02-12T14:24:23.476Z","subscription":{"href":"https://integration1.api.manheim.com/subscriptions/id/551b1b0e0cc15d2562ff37e66ed8fc7a"},"subscriber":{"href":"https://integration1.api.manheim.com/subscribers/id/4bb74dbc-4e85-11e6-a2d8-4b25d26238e1"}},"expansions":[]

5_Subscription:

{
    "subscriber": {
        "href": "https://integration1.api.manheim.com/subscribers/id/1b76f3de-0aac-11e8-8765-2d7426abad32"
    },
    "criteria": [
        {"type": {"pattern": "OFFERINGS.PURCHASED"}},         
           {"richFilter": "body.status == 'SOLD' && body.channel == 'OVE' && body.unit.vin == 'WVWC919XXXXX'"}

    ]
}

6_Note the path for rich Filter query parameters that matches exactly with path & value of the desired fields in the event structure.

7_Subscribers will receive all OFFERINGS.PURCHASED event associated with their company href or the related Manheim Account Numbers in subscription & have the given VIN with sold status on OVE channel.

Steps to add rich Filter criteria ​

  • When creating Subscription:
  • Primary Criteria: Resource or Type or Text. This needs to be added to the subscription first.
  • Add Rich Filter- The JMES path query string uses a key-value structure.
  • For subscription to event match : the qualifier path for Key in Rich Filter will match that in event structure.
  • A company id href or related Manheim Account Numbers associated with client's token are automatically added as resource to the subscription.
Example 1 ​

1_Subscriber requires: a. Offerings.Purchased event for channel=INLANE, when the status in the event is "OT_SOLD"(it can be any other status). b. Offerings.Purchased event when channel is any other (not INLANE) & all status.

2_Create Subscriber (see subscriber documentation) Subscriber creates 2 subscriptions here:

  • One Subscription to send event for inlane channel for all status not equal to NOT_SOLD.

Create Subscription:

{
    "subscriber": {
        "href": "https://integration1.api.manheim.com/subscribers/id/1b76f3de-0aac-11e8-8765-2d7426abad32"
    },
    "criteria": [
        {"type": {"pattern": "OFFERINGS.PURCHASED"}},
        
        {"richFilter": "body.status != 'NOT_SOLD' && body.channel == 'INLANE'"}
]
}
  • 2nd Subscription to send event for all channel other than INLANE & any status.

Create Subscription:

{
    "subscriber": {
        "href": "https://integration1.api.manheim.com/subscribers/id/1b76f3de-0aac-11e8-8765-2d7426abad32"
    },
    "criteria": [
        {"type": {"pattern": "OFFERINGS.PURCHASED"}},
        
        {"richFilter": "body.channel != 'INLANE'"}
]
}

3

  • Together Subscription 1 & 2 will allow customer to receive OFFERINGS.PURCHASED event for any status when channel is not equal to INLANE. Get the event for INLANE channel for all status other than NOT_SOLD.
  • Note: Customer gets all events that match above criteria & are associated with their company href or the related Manheim Account Numbers in subscription.
Example 2: ​

1_Subscription Requirement: Create subscription that lets customer know about purchase information & operation location for a particular vehicle.

2_Subscription using richFilter:

{
    "subscriber": {
        "href": "https://api.manheim.com/subscribers/id/1b76f3de-0aac-11e8-8765-2d7426abad32"
    },
    "criteria": [
        {"type": {"pattern": "OFFERINGS.PURCHASED"}},
        
        {"richFilter": "body.status == 'SOLD' && body.channel == 'INLANE' && body.consignment.operatingLocation.href == 'https://api.manheim.com/locations/id/XXX'"}
]
}

3_Note Rich Filter query path is based on how the fields are mentioned in the base OFFERINGS.PURCHASED event (below).

"body": {
  "href": "https://api.manheim.com/offerings/in-lane/id/e5e34ce8-0aa8-11e8-aa89-176258d45026",
  "purchasePrice": 56800,
  "status": "SOLD",
  "unit": {
    "href": "https://api.manheim.com/units/id/e86983da-fd31-11e7-b90f-25028bb70f0b",
    "vin": "WDDUG8FB7FA126238",
    "account": {
      "href": "https://api.manheim.com/contacts/id/f6ce5511-0d69-404c-80c9-63f5f72eee6e/account",
      "customer": {
        "href": "https://api.manheim.com/contacts/id/f6ce5511-0d69-404c-80c9-63f5f72eee6e/company"
      }
    }
  },
  "buyerAccount": {
    "account": {
      "href": "https://api.manheim.com/contacts/id/7e2d8582-7933-4ebb-8b66-f501b98c9ae2/account",
      "customer": {
        "href": "https://api.manheim.com/contacts/id/7e2d8582-7933-4ebb-8b66-f501b98c9ae2/company"
      }
    }
  },
  "consignment": {
    "href": "https://api.manheim.com/consignments/id/e3388288-0aa8-11e8-bb4f-25d350679607",
    "operatingLocation": {
      "href": "https://api.manheim.com/locations/id/RSAA"
    }
  },
  "purchaseDate": "2018-02-05T14:15:06.000Z"
},
"createdOn": "2018-02-05T19:15:17.070Z",
"subscription": {
  "href": "https://api.manheim.com/subscriptions/id/93061902f7fa56f1bd3e308b94f318d6"
},
"subscriber": {
  "href": "https://api.manheim.com/subscribers/id/995b9e60-83f6-11e5-a833-13b416b5de9c"
}

4 -All events that match on subscription criteria are published on the callback. -Note: Customer gets all the events that match above criteria & are associated with their company href or the related Manheim Account Numbers n subscription.

Example 3: ​

1_Subscriber needs event notification for vehicles that are of type - PASSENGER_VEHICLE, checked in by dealer- 5160XX on the given checked in date - 2014-04-01 with vehicle model year = 2007

2_The Primary Subscription criteria is CONSIGNMENTS.CHECKEDIN event as the business case is around vehicle checkedin.

3_Set the Secondary Subscription criteria (richFilter query)based on Consignments.Checkedin event field structure/path. Fields: body.unit.type,body.manheimAccountNumber, body.checkInDate, body.unit.description.modelYear

4_CONSIGNMENTS.CHECKEDIN event structure:

"body": {
  "href": "https://integration1.api.manheim.com/events/id/97f77250-1004-11e8-8a54-05a6cd617878",
  "eventType": "CONSIGNMENTS.CHECKEDIN",
  "body": {
    "href": "https://integration1.api.manheim.com/consignments/id/96fa7e42-1004-11e8-9708-6fb2e170c8a9",
    "unit": {
      "href": "https://integration1.api.manheim.com/units/id/96cfae6a-1004-11e8-b783-1de56b7a840b",
      "owner": {
        "href": "https://integration1.api.manheim.com/contacts/id/378f91cf-a384-42b0-90c9-e649fc623e2b/company"
      },
      "type": "PASSENGER_VEHICLE",
        "vin": "TESTVIN59f84d9eXXXXXX",
      "description": {
        "modelYear": 2007,
        ......
    },
      "checkInDate": "2014-04-01",
    "status": "CHECKED_IN",
    "operatingLocation": {
      "href": "https://integration1.api.manheim.com/locations/id/QMM1"
    },
    "customerId": "344710",
    "manheimAccountNumber": "5160XX",
       ....
     ....
    },
    "type": "CONSIGNMENTS.CHECKEDIN"
  },
  "createdOn": "2018-02-12T14:54:15.029Z",
  "subscription": {
    "href": "https://integration1.api.manheim.com/subscriptions/id/9e20ce3478d1571875aa69eb005b78ca"
  },
  "subscriber": {
    "href": "https://integration1.api.manheim.com/subscribers/id/32e1a14e-76e7-11e7-8311-6bfe13172b00"
  }
}, "expansions": []
}

5_Resulting Subscription:

{
    "subscriber": {
        "href": "https://integration1.api.manheim.com/subscribers/id/1b76f3de-0aac-11e8-8765-2d7426abad32"
    },
    "criteria": [
        {"type": {"pattern": "CONSIGNMENTS.CHECKEDIN"}},
        
        {"richFilter": "body.unit.type == 'PASSENGER_VEHICLE' && body.unit.description.modelYear == '2007'&& body.manheimAccountNumber == '5160XX' && body.checkInDate == '2014-04-01'"}
]
}

6_The subscription criteria will be matched with CONSIGNMENTS.CHECKEDIN events that have the key-value pair/path & the stated company href or Manheim Account Numbers (that are automatically added in subscription).

Example 4 ​

1_Business Case- Subscribers wants event notification for vehicles checked in at location code AAA or that checked in at location code BBB

2_The Primary Subscription criteria is CONSIGNMENTS.CHECKEDIN event as the business case is around vehicle checkedin.

3_Set the Secondary Subscription criteria (richFilter query)based on location requirement.. Fields: body.operatingLocation

4_CONSIGNMENTS.CHECKEDIN event structure:

"body": {
  "href": "https://integration1.api.manheim.com/events/id/97f77250-1004-11e8-8a54-05a6cd617878",
  "eventType": "CONSIGNMENTS.CHECKEDIN",
  "body": {
    "href": "https://integration1.api.manheim.com/consignments/id/96fa7e42-1004-11e8-9708-6fb2e170c8a9",
    "unit": {
      "href": "https://integration1.api.manheim.com/units/id/96cfae6a-1004-11e8-b783-1de56b7a840b",
      "owner": {
        "href": "https://integration1.api.manheim.com/contacts/id/378f91cf-a384-42b0-90c9-e649fc623e2b/company"
      },
      "type": "PASSENGER_VEHICLE",
        "vin": "TESTVIN59f84d9eXXXXXX",
      "description": {
        "modelYear": 2007,
        ......
    },
      "checkInDate": "2014-04-01",
    "status": "CHECKED_IN",
    "operatingLocation": {
      "href": "https://integration1.api.manheim.com/locations/id/QMM1"
    },
    "customerId": "344710",
    "manheimAccountNumber": "5160XX",
       ....
     ....
    },
    "type": "CONSIGNMENTS.CHECKEDIN"
  },
  "createdOn": "2018-02-12T14:54:15.029Z",
  "subscription": {
    "href": "https://integration1.api.manheim.com/subscriptions/id/9e20ce3478d1571875aa69eb005b78ca"
  },
  "subscriber": {
    "href": "https://integration1.api.manheim.com/subscribers/id/32e1a14e-76e7-11e7-8311-6bfe13172b00"
  }
}, "expansions": []
}

5_Resulting Subscription:

{
    "subscriber": {
        "href": "https://integration1.api.manheim.com/subscribers/id/1b76f3de-0aac-11e8-8765-2d7426abad32"
    },
    "criteria": [
        {"type": {"pattern": "CONSIGNMENTS.CHECKEDIN"}},
        
        {"richFilter": "body.operatingLocation.href == 'https://integration1.api.manheim.com/locations/id/AAA' || body.operatingLocation.href == 'https://integration1.api.manheim.com/locations/id/BBB'"}
]
}

6_The subscription will match with CONSIGNMENTS.CHECKEDIN events that have the key-value pair/path & the stated company href or related Manheim Account Numbers(that are automatically added in subscription).

richFilter query operators (including but not restricted to): ​

OperationOperation DefinitionQuery Operator
ANDParameter A & B be true&&
ORParameter A or B be true||
Not EqualParameter A not equal to B!=
Equal toParameter A equal to B==
Compare a Number"field" == A numbers (1232)"field"== 1234
ComparatorGreater than, Less than, Greater than equal to, Less than equal to<, <=, >, >=

Common error scenarios for richFilter ​

Scenario 1. Rich Filter is passed as blank "" Subscription:

{"subscriber":{"href":"https://uat.api.manheim.com/subscribers/id/cfda1b86-0ab0-11e8-8965-798964ecac9d"},"criteria":[{"text":"vin"},{"richFilter":" "}],"inactive":false,"expansions":["body.unit"]}

Response when creating Subscription: Error creating subscription!! - 400 --

{"errors":[{"message":"Rich filter expression is not valid","developerMessage":"Rich filter expression is not valid"}]}

Scenario 2. Rich Filter is passed as 0 Subscription:

{"subscriber":{"href":"https://uat.api.manheim.com/subscribers/id/cfda1b86-0ab0-11e8-8965-798964ecac9d"},"criteria":[{"text":"vin"},{"richFilter":0}],"inactive":false,"expansions":["body.unit"]}

Response when creating Subscription: Error creating subscription!! - 400 --

{"errors":[{"message":"Rich filter expression is not valid","developerMessage":"Rich filter expression is not valid"}]}

Scenario3: Rich Filter is set as null.

Subscription:

{"subscriber":{"href":"https://uat.api.manheim.com/subscribers/id/cfda1b86-0ab0-11e8-8965-798964ecac9d"},"criteria":[{"text":"vin"},{"richFilter":"body.wo != null OR body.vin != null"}],"inactive":false,"expansions":["body.unit"]}

Response when creating Subscription: Error creating subscription!! - 400 --

{"errors":[{"message":"Rich filter expression is not valid","developerMessage":"Rich filter expression is not valid"}]}

Scenario4: Client creates subscription using Rich Filter & does not provide primary criteria- Resource, Type or Text.

Subscription:

{"subscriber":{"href":"https://uat.api.manheim.com/subscribers/id/cfda1b86-0ab0-11e8-8965-798964ecac9d"},"criteria":[{"richFilter":"body.wo != null OR body.vin != null"}],"inactive":false,"expansions":["body.unit"]}

Response when creating Subscription: Error creating subscription!! - 400 --

{"errors":[{"message":"Rich filter expression is not valid","developerMessage":"Rich filter expression is not valid"}]}

Business Scenarios for Creating Subscriptions ​

Example 1 ​

Customer wants to be notified when a vehicle belonging to their company checks in at the auction:

  • To receive events that notify customer - A subscription with event type:CONSIGNMENTS.CREATED & company(ABC) resource url must be created.
  • Once the events that successfully match the subscription criteria: event body contains particular event type AND company resource url will only be sent to callback
  • All filter criteria provided require to be matched for events to be selected.
POST https://api.manheim.com/subscriptions
{
    "subscriber": {
        "href": "https://api.manheim.com/subscribers/id/a3a331c0-2579-11e5-bf3e-51a3ec343242"
    },
    "criteria": [
        {
            "type": {
                "pattern": "CONSIGNMENTS.CREATED"
            }
        },
        {
            "resource": {
                "href": "https://api.manheim.com/companies/id/ABC"
            }
        }
    ]
}

Example 2 ​

Customer wants to be notified when the vehicle belonging to their company checks in at a Atlanta auction:

  • To receive events that notify customer about the scenario- subscription with event type: CONSIGNMENTS.CREATED & company(ABC) resource url & auction location url needs to be created.
  • Only the events that successfully where event body contains the particular event type AND company resource ur AND auction location url will only be sent to callback
  • All filter criteria provided must be matched for events to be selected.
POST https://api.manheim.com/subscriptions
{
    "subscriber": {
        "href": "https://api.manheim.com/subscribers/id/a3a331c0-2579-11e5-bf3e-51a3ec34b787"
    },
    "criteria": [
        {
            "type": {
                "pattern": "CONSIGNMENTS.CREATED"
            }
        },
        {
            "resource": {
                "href": "https://api.manheim.com/locations/id/AAA"
            }
        },
         {
            "resource": {
                "href": "https://api.manheim.com/companies/id/123"
            }
        }

    ]
}

Example 3 ​

Customer wants to know the floor price set for a particular vehicle(unit id):

  • Customer can create subscription for event type:OFFERINGS.CREATED and company(ABC) resource url and particular unit id url.
  • Only the events that successfully match the subscription criteria where event body contains particular event type AND company resource ur AND unit id url will be sent to callback
  • All filter criteria provided require to be matched for events to be selected.
POST https://api.manheim.com/subscriptions 

{
    "subscriber": {
        "href": "https://api.manheim.com/subscribers/id/a3a331c0-2579-11e5-bf3e-51a3ec34b787"
    },
    "criteria": [
        {
            "type": {
                "pattern": "OFFERINGS.CREATED"
            }
        },
        {
            "resource": {
                "href": "https://api.manheim.com/companies/id/AB123"
            }
        },
        {
            "resource": {
                "href": "https://api.manheim.com/unit/id/ABC1234"
            }
        }
    ]
}

Example 4 ​

Customers wants to know notification for auction processes for a given unit (inventory).

  • Customer can create subscription for the particular unit id url. Customer needs to know the unit url for this subscription.
  • Only the events that successfully match the subscription criteria: event body contains particular unit id url will be sent to callback
  • All filter criteria provided require to be matched for events to be selected.
POST https://api.manheim.com/subscriptions 

{
    "subscriber": {
        "href": "https://api.manheim.com/subscribers/id/a3a331c0-2579-11e5-bf3e-51a3erweeqw"
    },
    "criteria": [
       {
            "resource": {
                "href": "https://api.manheim.com/unit/id/ABC1234"
            }
        }
    ]
}

Example 5 ​

Customer wants to be notified about Offerings scenarios

  • To receive events for the given scenario, subscription with event type: OFFERINGS.* & company(ABC) resource url needs to be created.
  • OFFERINGS.* will take care of all Offering scenario & customer does not require to create subscription for each scenario.
  • Only the events that successfully match the subscription criteria: event body contains particular event type AND company resource url AND auction location url will only be sent to callback
  • All filter criteria provided require to be matched for events to be selected.
POST https://api.manheim.com/subscriptions 

{
    "subscriber": {
        "href": "https://api.manheim.com/subscribers/id/a3a331c0-2579-11e5-bf3e-51a3ec34b787"
    },
    "criteria": [
        {
            "type": {
                "pattern": "OFFERINGS.*"
            }
        },
        {
            "resource": {
                "href": "https://e2e.api.manheim.com/companies/id/123"
            }
        }

    ]
}

Example 6 ​

Customer wants to know when an offering is made on a particular car(VIN).

  • Customer can create subscription by type- OFFERINGS.CREATED & text-VIN & resource as company id url
  • Only the events that successfully match the subscription criteria: event body contains particular type,company id url & text value will be delivered to the callback.
POST https://api.manheim.com/subscriptions 

{
    "subscriber": {
        "href": "https://api.manheim.com/subscribers/id/a3a331c0-2579-11e5-bf3e-51a3ec34b787"
    },
    "criteria": [
        {
            "type": {
                "pattern": "OFFERINGS.CREATED"
            }
        },
        {
            "text": "2GNALPEC2BC63DED8"
        },
        {
            "resource": {
                "href": "https://api.manheim.com/companies/id/123"
            }
        }
    ]
}

Update a Subscription for customer with external scope ​

Endpoint ​

POST /subscriptions/id/\<ID>lt;ID\<ID>gt;

Description ​

  • Customer can update an existing subscription's **inactive ** field:
    • set inactive to true if subscription requires to be inactivated
    • set inactive to false if the inactivated require to be reactivated.
    • Customer do not receive events on callback for subscriptions where inactive equal to true status.
    • Customer can choose to reconcile events via the events endpoint for subscription with inactive set to true status.
  • Customer must execute a POST in JSON format (for mentioned fields) to the particular subscription id url for updates.
  • On successful update, there will be 200 ok response is returned.

Example for updating a subscription's inactive field ​

POST https://api.manheim.com/subscriptions/id/\<ID>lt;ID\<ID>gt;
{
        "inactive" : "false"
}

Common Return Codes ​

The Subscriptions API generally returns standard HTTP status codes.

  • 204 No Content: A successful response indicating that the subscription has been updated.
  • 400 Bad Request: ERROR: the subscription cannot be updated, possibly because of a malformed JSON object.
  • 403 Forbidden: ERROR: the user is not authorized to modify this subscription.
  • 404 Not Found: ERROR: the requested subscription was not found.

Some business scenarios where Update for a subscription is applied ​

Example1 ​

The customer wants to put on hold the flow of events on the callback for UNIT.CREATED event type for a company ABC due to business decisions:

  • Customer can execute the POST to the particular subscription id and set the inactive field equal to true.
  • While the inactive field is true, customer will not receive events on callback
  • Events will be available for reconciliation via events endpoint if customer chooses to do so.
  • Subscription can be re-activated by setting inactive field as false.
POST https://api.manheim.com/subscriptions/id/\<ID>lt;ID\<ID>gt;
{
     "inactive": "true"
}

Retrieve a Subscription ​

Endpoint ​

GET /subscriptions/id/ID
GET /subscriptions/mine

or

GET /subscriptions/mine?limit=N
GET /subscriptions/subscriber/\<id>lt;id\<id>gt;

or

GET /subscriptions/subscriber/\<id>lt;id\<id>gt;?limit=N

Description ​

  • Retrieval endpoints are available for subscriptions.
  • Customer can execute a GET on the subscription by ID endpoint & retrieve information about the subscription.
  • Customer can execute a GET on the subscription/mine endpoint & retrieve information for all subscriptions across subscribers belonging to them.
  • Customer can execute GET on subscriptions/subscriber id to get details of all subscriptions under a given subscriber id.
  • For subscriptions/mine & subscription/subscriber/<id>lt;id<id>gt; endpoints:
    • These endpoints supports limit for pagination. The max limit for page view is 500.
    • The endpoint will provide a max of 500 items on the page even if the ask limit is > 500.
    • The default pagination value is 25 if no limit is provided.

Common Return Codes ​

Response CodeDescriptionPossible Next Actions
201 CreatedSuccessful responseNo action necessary
400 Bad RequestRequired parameter missing or parameter data type incorrect; response body describes errorMake the necessary corrections and re-submit the request
401 UnauthorizedAccess denied due to incorrect credentials, malformed API token, or because user does not have accessValidate the token or contact us for API access
404 Not FoundData specified in the request was not foundModify request and resubmit
415 Unsupported Media TypeMessage contains details about what content type is not supportedRequest must be in JSON format; confirm that Content-Type header is set as application/json; reformat and resubmit
503 Service UnavailableThe application server rejected the connection or there is a SQL exceptionEnsure that the request is valid and resubmit. If the problem persists, contact your Manheim support representative

NOTES

  • 200 OK: A successful response with the requested subscription; the response includes the subscription in JSON representation similar to the Example JSON code below.
  • 404 Not Found: ERROR: the requested subscription was not found.

Example of retrieval of subscription information by ID endpoint ​

GET https://api.manheim.com/subscriptions/id/\<ID>lt;ID\<ID>gt;
{
  "href": "https://api.manheim.com/subscriptions/id/6ba5937bf5a309a7XXXXXXXX",
  "subscriber": {
    "href": "https://api.manheim.com/subscribers/id/9efe9ef0-93b8-11e4-9f2e-XXXXXXXX"
  },
  "criteria": [
    "ORDERS.TRANSPORTATION.CANCELLED"
  ],
  "eventsLastMatched": "2018-11-11T23:59:59.500Z",
  "createdOn": "2015-01-04T02:25:25.000Z",
  "updatedOn": "2018-11-12T22:49:49.769Z"
}

Example of retrieval of events by subscription/mine endpoint ​

GET https://api.manheim.com/subscriptions/mine?limit=1
{
  "href": "https://api.manheim.com/subscriptions/mine?limit=25",
  "limit": 25,
  "items": [
    {
      "href": "https://api.manheim.com/subscriptions/id/18f61516XXXXXXXX",
      "subscriber": {
        "href": "https://api.manheim.com/subscribers/id/12de211c-4152-11e7XXXXXXXX"
      },
      "criteria": [
        "TESTEVENT.ALL"
      ],
      "expansions": [
        "body.unit"
      ],
      "eventsLastMatched": "2018-11-09T00:00:00.000Z",
      "createdOn": "2017-05-25T14:02:20.235Z",
      "updatedOn": "2017-05-25T14:02:20.238Z"
    }
  ]
}

Example of retrieval of subscription by subscriber id ​

GET https://api.manheim.com/subscriptions/subscriber/\<id>lt;id\<id>gt;?limit=1
{
  "href": "https://api.manheim.com/subscriptions/subscriber/9efe9ef0-93b8-11e4-9f2e-XXXXXXXXXXX?limit=25",
  "limit": 25,
  "items": [{
      "href": "https://api.manheim.com/subscriptions/id/6ba5937bf5a309a72e5cXXXXXXXX",
      "subscriber": {
        "href": "https://api.manheim.com/subscribers/id/9efe9ef0-93b8-11e4-XXXXXXXX"
      },
      "criteria": [
        "ORDERS.TRANSPORTATION.CANCELLED"
      ],
      "eventsLastMatched": "2018-11-04T23:59:59.500Z",
      "createdOn": "2015-01-04T02:25:25.000Z",
      "updatedOn": "2018-11-05T04:55:15.935Z"
    },
    {
      "href": "https://api.manheim.com/subscriptions/id/250b4c811bc1d234d00XXXXXXX",
      "subscriber": {
        "href": "https://api.manheim.com/subscribers/id/9efe9ef0-93b8-11e4-9f2e-XXXXXXXX"
      },
      "criteria": [
        "ORDERS.TRANSPORTATION.CREATED"
      ],
      "eventsLastMatched": "2018-11-04T23:59:59.500Z",
      "createdOn": "2015-01-04T02:28:11.000Z",
      "updatedOn": "2018-11-05T04:55:16.102Z"
    },
    {
      "href": "https://api.manheim.com/subscriptions/id/3aeeac1c0a686b4745eXXXXXX",
      "subscriber": {
        "href": "https://api.manheim.com/subscribers/id/9efe9ef0-93b8-11e4-9f2e-XXXXXXX"
      },
      "criteria": [
        "ORDERS.TRANSPORTATION.UPDATED"
      ],
      "eventsLastMatched": "2018-11-04T23:59:59.500Z",
      "createdOn": "2015-01-04T02:28:51.000Z",
      "updatedOn": "2018-11-05T04:55:16.251Z"
    }
  ]
}

Delete a Subscription ​

Endpoint ​

DELETE /subscriptions/id/\<ID>lt;ID\<ID>gt;

Description ​

  • Customer can delete a particular subscription if the event result set is no longer required for client business.
  • Once the subscription is deleted, customer neither receives the matching events on callback nor via reconciliation endpoints.
  • Customer must execute a DELETE on the particular subscription id url that requires deletion.
  • On successful delete, the customer will receive 200 ok response.
  • After a successful deletion, to restart the events on callback for the same filter criteria, the customer would require to re-create their subscription with the required criteria.

Common Return Codes ​

The Subscriptions API generally returns standard HTTP status codes.

  • 204 No Content: A successful response that the subscription has been deleted.
  • 400 Bad Request: ERROR: the requested subscription has been found but cannot be deleted.
  • 403 Forbidden: ERROR: the user is not authorized to modify this subscription.
  • 404 Not Found: ERROR: the requested subscription was not found.

Duplicate a Subscription (Error) ​

Customer will not be allowed to create duplicate subscription for a particular subscriber.

Description ​

  • Customer creates subscription with criteria option & value same as that of an existing subscription (for a given subscriber).
  • The new subscription will be rejected as there exists a subscription with same criteria
  • New subscription gets rejected as this is redundant. This & the existing will provide the same event result-set.
  • Customer receives response with 409 Error Code with Error Message.
  • The response contains the existing subscription id url in location header.

1_Subscriber id: "https://api.manheim.com/subscribers/id/1232" 2_GET on Existing Subscription: "https://api.manheim.com/subscriptions/id/234314 3_Customer creates new Subscription for this subscriber:

The new subscription gets rejected as there exists a subscription with same criteria for the given subscriber.

Common Return Codes ​

The Subscriptions API generally returns standard HTTP status codes.

  • 400 Bad Request: ERROR: the requested subscription has been found but cannot be deleted.