Dealer Reviews Collection

This is a consumer-oriented API that can be used to fetch or create reviews on our server for a given dealer.

/Dealers/[dealerId]/Reviews

Attribute	Description
dealerId	Set this to the ID of the dealer to fetch reviews for.

For example, the URL for the reviews collection for dealer ID 47 is /Dealers/47/Reviews.

Common Request Parameters

All APIs support the following request parameters, in addition to any API specific parameters.

Parameter	Description	Example
t	json or xml. Identifies if you want to communicate in JSON or XML format.	t=xml
s	Your DealerRater supplied security token. This must be sent with every request.	s=00000000-0000-0000-0000-000000000000
method	GET, INSERT, UPDATE or DELETE. Identifies the REST verb.	method=GET

GET

This API is used to retrieve a paginated list of reviews for a given dealer. A variety of mechanisms are available to filter the returned data as well. Note that the results of this API are cached on the DealerRater servers for optimization purposes (as such, new reviews posted to dealers might not be available through this API for a short while). The results are always returned with the latest reviews first, with older reviews following in descending chronological order.

Request Parameters

Parameter	Description	Example	Default
startItem	Used to identify the first item in the paged collection to be returned. If you set this to 20, then the response will include reviews starting at review #20.	startItem=20	0
itemsPerPage	Identifies the number of items to be returned with each page of results.	itemsPerPage=20	MAX_INT
filterReviewType	Applies a filter on the type of review. ALL_REVIEWS returns all the reviews; ONLY_POSITIVE returns only positive reviews; ONLY_NEGATIVE returns only negative reviews; ONLY_SALES returns all new and used sales reviews; and ONLY_SERVICE returns only service reviews.	filterReviewType=ONLY_POSITIVE	ALL_REVIEWS
filterEmployeeIds	A comma separated list of employee IDs to filter the returned list of reviews by.	filterEmployeeIds=1,2,3	N/A

Request XML/JSON

This API does not accept XML or JSON data in the request.

Response

The API will respond with an XML or JSON document with the reviews matching the given request criteria. A sample XML response is indicated in the code block below, with a downloadable sample mock provided in either XML or JSON format. Note that the response document will include references to the following object types:

Entity	Description
Status	API call status.
PagingContext	Paging criteria.
Review	Defines a single Review in the system.
ReviewPageUrl	The URL in DealerRater's system that is home to all of the reviews for this dealer.

<DealerReviewsGetCollectionResponse>
  <Status>...</Status>
  <PagingContext>...</PagingContext>
  <ReviewPageUrl>http://www.dealerrater.com/dealer/Bozard-Ford-Lincoln-review-2259/</ReviewPageUrl>
  <Reviews>
    <Review>...</Review>
    <Review>...</Review>
    <Review>...</Review>
  </Reviews>
</DealerReviewsGetCollectionResponse>

INSERT

Use this API to create new reviews for the given dealer. If you need to create reviews for multiple dealers (different dealer IDs), you will need to make one call for each dealer, but each call can be used to post multiple reviews to the same dealer ID. The reviews that are created on the server might not be immediately available via our GET API (above) for some time as a result of:

Caching
If a call had been made to fetch the review content for this dealer already, the stale content might already be cached on the server. Caches purge every several minutes.
Review Content
Depending on the specific review content, it is possible that the review might not "go live" on our website for some amount of time (as a result of our profanity filtering, fraud detection, and other business logic we run on all incoming reviews).

Please be aware of the attributes marked for write and which of those attributes are required on the Review entity.

NOTE: For server stability and load balancing reasons, we have opted to impose a maximum 10 review per-request limit. Any call to the server attempting to create more than 10 reviews for a single request will result in a failure.

Request Parameters

This API accepts the following parameters:

Parameter	Description	Example	Default
data	The XML or JSON request payload defining the reviews to be created. The data should be URL encoded in the POST block.	See below for an un-encoded example.	N/A, this parameter is required.

Request XML/JSON

The request payload contains XML or JSON content that define the reviews you will be creating in our system. A sample XML request is indicated in the code block below, with a downloadable sample mock provided in either XML or JSON format (although it is not shown in the linked mocks, you must submit the XML or JSON content URL encoded in a POST block assigned to the data parameter; an example of how to do this is provided above). Note that the request document will include references to the following object types:

Entity	Description
Review	Defines a review to be created. Take special note of the documentation in the entity so you know what fields are to be passed when creating the reviews. Some fields are required and must be passed, while others are optional.

<DealerReviewsInsertCollectionRequest xmlns="http://partner.dealerrater.com">
  <Reviews>
    <Review>...</Review>
    <Review>...</Review>
    <Review>...</Review>
  </Reviews>
</DealerReviewsInsertCollectionReques>

NOTE: Our xmlns is required on the root element for the POST to succeed. In addition, the XML serialization engine requires that all elements in the XML document be ordered alphabetically. Failure to post elements with the root xmlns or with elements out of order can result in unexpected server behavior. These restrictions do not apply to JSON.

Validation

The server first performs a pre-check validation on all reviews being submitted to ensure conformity to our requirements (make sure that all required fields are present, that strings are no longer than the max length, email addresses are properly formatted, etc). If any review being submitted in the request fails the pre-check validation, the entire request will fail with a validation error. Assuming validation passes, we push each review through our submission process. On very rare occcasions, backend processes that are responsible for accepting the review might fail. In such a circumstance, the review that was unable to be submitted will be returned in the response below in the FailedReviews element. We provide this information to you in order to aid us in debugging production issues should a problem arise -- having reviews come back in the FailedReviews element should be considered an exceptional case. Any reviews that are returned in this collection will include a "ErrorCode" that, when provided to our support staff, can be used to track down issues on our server and will give us more information on why particular review INSERT requests might be failing.

If you want to avoid failing the entire request due to validation failures, you will need to make a single request to this API for each review you want to create. This will ensure that any validation failures that happen on one review will not impact the submission of others that might otherwise be in the batch.

Response

The API will respond with an XML or JSON document with the results of the request. As indicated above, if there are any validation failures for any of the reviews, the entire request will fail. A sample XML response is indicated in the code block below, with a downloadable sample mock provided in either XML or JSON format. Note that the response document will include references to the following object types:

Entity	Description
Status	API call status.
Review	A review that was created or might have failed.

<DealerReviewsInsertCollectionResponse>
  <Status>...</Status>
  <SuccessfulReviews>
    <Review>...</Review>
    <Review>...</Review>
    <Review>...</Review>
  </SuccessfulReviews>
  <FailedReviews>
    <FailedReview>
      <ErrorCode>...</ErrorCode>
      <Review>...</Review>
    </FailedReview>
  </FailedReviews>
</DealerReviewsInsertCollectionResponse>

UPDATE

This API does not support the UPDATE verb.

DELETE

This API does not support the DELETE verb.