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 |
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. |
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.
|
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.
|
UPDATE
This API does not support the UPDATE verb.
DELETE
This API does not support the DELETE verb.