The Review APIs will be the record of store for Cars.com reviews, as well as data that is closely aligned with those reviews (things like public messages, ratings, etc). The APIs will only return reviews (and other data) that are flagged for being publicly visible on consumer facing websites.
These APIs should be utilized by external vendors for doing things like creating new dealer reviews, adding, updating and deleting review responses and fetching reviews.
You'll need to be careful to ensure you're calling the correct service host and passing the correct security token(s) (see below) in order for the API invocation to succeed. All API calls must flow over an HTTPS secure channel; non-secure connections are not supported.
\nThe production environment should only be utilized by code in your production environment. The hostname for this environment is services.dealerrater.com. You should not be running any active development, test, staging, integration or other lower-tier environments against production.
If you need to test your changes before deploying them to production, you can contact DealerRater help desk at help@dealerrater.com to request access to test environment APIs.
Every API released in this service will require at least one, but sometimes two, modes of authorization.
\nEvery single API will require that you have a valid API key in order to make it through the gateway. You need to contact DealerRater help desk to get this key. This key should be sent along with every request as an x-api-key HTTP header. Note that you may have separate API keys for accessing our different environments, so please make sure you're using the correct one.
The more sensitive APIs (anything that mutates data in our datastore) will require you to be granted explicit authorization through our security service. Using that service you can request an access token that will be valid for one hour. To learn more about JWT tokens and to decode them and see what is inside, visit jwt.io. The Security API that needs to be called to get the Access token is explained in the Security API section.
\nImportant: While calling the Security API to get the access token, proper Scope should be passed in the request. The scope should be of the following format: \"rvw/dealer:cars:12345\", where the number 12345 is the CCID of the dealer to be associated with the Review API calls. The access token generated with this scope will work only for this particular dealer. For different dealer, you will need to call the Security API with different scope to get a new access token. You could very well have a system that needs to integrate with a handful (hundreds, maybe thousands) of dealer IDs. The access tokens given to these usecases are valid for a full hour. You have a couple options - you can generate all the tokens you need upfront and cache them (assuming your integration will only be scoped to an ~hour or so) or you could more smartly group your calls by dealer ID, creating a token as needed - use it - then discard the token and create a new one for the next batch of calls for a different Dealer ID.
\nAll APIs will return one of the following response codes.
\nThis code indicates a successful operation.
\nFor data mutation commands that create data in our system, you can expect a 201 success code instead of a 200 code.
\nAn error was detected with the request, either a malformed payload, incorrect or missing form parameters, etc. Inspect the response to determine the root cause, adjust your API call and try again.
\nThe client attempted an operation for which it is not authorized. All of our APIs require a valid AWS API Gateway key to be submitted via the x-api-key header with your request, and some of the more sensitive APIs require full JWT tokens granted to you via our security service. Ensure all of these are handled per requirements and try again.
The client is calling our services faster than the rate limit we have assigned. The caller should implement a backoff algorithm, slow down, and try again.
\nAn unexpected server error occurred. You should log the x-correlation-id response header (a unique GUID we assign for each request) to your logs and provide that to a DealerRater developer. We can easily track that entire request chain in our logs to determine root cause and take corrective action.
The request must be submitted using this Content-Type.
\n"},{"key":"x-api-key","value":"{{ApiKey}}","description":"The API key you were issued by DealerRater.
\n"}],"body":{"mode":"urlencoded","urlencoded":[{"key":"grant_type","value":"client_credentials","description":"The grant_type must be set to client_credentials to request this type.
The client ID you were issued by DealerRater.
\n","type":"text"},{"key":"client_secret","value":"{{ClientSecret}}","description":"The client secret you were issued by DealerRater.
\n","type":"text"},{"key":"scope","value":"rvw/dealer:cars:1234","description":"What scope(s) you would like the access token to include. For the Review APIs, the scope should be of the following format: \"rvw/dealer:cars:12345\", where the number 12345 is the CCID of the dealer to be associated with the Review API calls. The access token generated with this scope will work only for this particular dealer. For different dealer, you will need to call the Security API with different scope to get a new access token.\nYou could very well have a system that needs to integrate with a handful (hundreds, maybe thousands) of dealer IDs. The access tokens given to these usecases are valid for a full hour. You have a couple options - you can generate all the tokens you need upfront and cache them (assuming your integration will only be scoped to an ~hour or so) or you could more smartly group your calls by dealer ID, creating a token as needed - use it - then discard the token and create a new one for the next batch of calls for a different Dealer ID.
\n","type":"text"}]},"url":"https://{{ServicesHost}}/security_v1/token","description":"This variant of the Token API can be used to obtain access tokens for trusted third parties. You will be issued two strings (a client ID and a client secret) that must be kept confidential. The returned access token will have a longer TTL lasting approximately one hour. The permissions issued in the token will be for the dealer present in the request scope. \nNOTE: You should call this API to get the Access Token for each dealership separately.\nTo issue a request of the client_credentials type, you must specify the following:
This API should be used to get the Access Token needed to call all the Review APIs, except Get Reviews API call. The Access Token generated will work only for the DealerId (CCID) present in the scope of this API call.
\n","event":[{"listen":"prerequest","script":{"type":"text/javascript","exec":[""],"id":"fe24773e-2d5f-46ac-b086-3d09255eb3c2"}},{"listen":"test","script":{"type":"text/javascript","exec":[""],"id":"7ec19f93-f9ea-49cf-ad94-33ccd8136205"}}],"_postman_id":"a1ff5cad-6dbc-4ae0-a7e4-d31f23dc2923"},{"name":"Dealer Review APIs","item":[{"name":"Cars.com","item":[{"name":"Ratings Collection","item":[{"name":"Get Dealer Ratings (GET)","id":"b730e7ad-88df-489d-be8b-7cc634e13e7a","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"description":"The API key you were issued by DealerRater, grating access through our API Gateway.
\n","key":"x-api-key","value":"{{ApiKey}}"},{"description":"The access token granting permissions to invoke this API endpoint, with permissions as outlined in the specification above.
\n","key":"Authorization","value":"Bearer {{AccessToken}}"}],"url":"https://{{ServicesHost}}/review_v1/dealers/c/reviews/ratings","description":"This API can be used to fetch the ratings that are currently configured for use on Cars.com dealer reviews (these are the individual 1-5 star categories such as Overall, Price, Quality, etc, that a consumer can rate a given dealer on). We are planning on adjusting these over time to give better metrics to dealers and help with review conversion.
\nThe rating categories returned here are to be used for rendering your review collection form. All ratings are configured per-Scope (SalesNew, SalesUsed and Service). Each review that is submitted is required to have a Scope set on it (one of the three listed above) and we will be changing these over time. When rendering your review form, you will need to ensure that the appropriate ratings are shown depending on which Scope the user has selected.
\nEach rating that is returned will also provide information on labels (what you should place in your UI when collecting the rating), whether each category is a required entry or an optional entry, and the JSON key to use for each when submitting the data to the review collection API (that information is documented in the New Dealer Review API).
\nDue to the more sensitive nature of this API compared to the consumer read-optimized database, you are required to submit a JWT token with the rvw_cars permission to successfully fetch ratings from this endpoint.
The API will deliver a single list of ratings in the response, an array under the Ratings property. Each object in that array is of the same type, and is defined below.
Each object in each of the Ratings arrays will provide you with three properties: Name, Label and Required, such as the following:
{\n \"Name\": \"BuyingProcess\",\n \"Label\": \"Buying Process\",\n \"Required\": false\n}\nIn the above example, we have a single rating.
\nBuying Process on your web formRequired is false, it is an optional entry; if this were true, you would be required to submit a value to the new review API, otherwise you'll get a validation errorBuyingProcess for the key in the JSON of the new review APINote that when rendering the ratings to the end-user on your review collection form, you will need to order them in some fashion. We would recommend that you do the following to increase conversion:
\nLabel alphabeticallyThis will ultimately be up to your individual User Experience staff, just note the API does not dictate any particular ordering. It will only tell you what ratings are supported, which are required, and how to submit them to our review collection endpoints.
\nScope: This is an optional query parameter that can be sent, and must be one of SalesNew, SalesUsed or Service. If omitted, the API will return the full rating configuration for all three scopes. If given, it will return only the configuration for the requested scope. When integrating with the API, you can either fetch the rating configuration and cache it in-browser while the user composes their review, switching ratings as necessary when the scope changes; or, you can invoke the API each time the user changes the scope, fetching only the ratings you need for that value.
\nA hypothetical response for a fetch call to this API that returns a set of dealer ratings is shown below:
\n{\n\"Scopes\": [\n {\n \"Scope\": \"SalesNew\",\n \"Ratings\": [\n {\n \"Name\": \"Overall\",\n \"Label\": \"Overall\",\n \"Required\": true\n },\n {\n \"Name\": \"CustomerService\",\n \"Label\": \"Customer Service\",\n \"Required\": false\n },\n {\n \"Name\": \"BuyingProcess\",\n \"Label\": \"Buying Process\",\n \"Required\": false\n },\n {\n \"Name\": \"QualityOfWork\",\n \"Label\": \"Quality Of Work\",\n \"Required\": false\n },\n {\n \"Name\": \"Facilities\",\n \"Label\": \"Facilities\",\n \"Required\": false\n }\n ]\n },\n {\n \"Scope\": \"SalesUsed\",\n \"Ratings\": [\n {\n \"Name\": \"Overall\",\n \"Label\": \"Overall\",\n \"Required\": true\n },\n {\n \"Name\": \"CustomerService\",\n \"Label\": \"Customer Service\",\n \"Required\": false\n },\n {\n \"Name\": \"BuyingProcess\",\n \"Label\": \"Buying Process\",\n \"Required\": false\n },\n {\n \"Name\": \"QualityOfWork\",\n \"Label\": \"Quality Of Work\",\n \"Required\": false\n },\n {\n \"Name\": \"Facilities\",\n \"Label\": \"Facilities\",\n \"Required\": false\n }\n ]\n },\n {\n \"Scope\": \"Service\",\n \"Ratings\": [\n {\n \"Name\": \"Overall\",\n \"Label\": \"Overall\",\n \"Required\": true\n },\n {\n \"Name\": \"CustomerService\",\n \"Label\": \"Customer Service\",\n \"Required\": false\n },\n {\n \"Name\": \"BuyingProcess\",\n \"Label\": \"Buying Process\",\n \"Required\": false\n },\n {\n \"Name\": \"QualityOfWork\",\n \"Label\": \"Quality Of Work\",\n \"Required\": false\n },\n {\n \"Name\": \"Facilities\",\n \"Label\": \"Facilities\",\n \"Required\": false\n }\n ]\n }\n]\n}\nIn the case of a successful fetch, you'll be given a 200 OK response code and the response payload will have the data as defined in this API.
A 400 Bad Request will be returned if there was a validation error. Please check the response payload to resolve the issue and try again.
There was an error with your JWT token.
\nThere was an error with your x-api-key API Gateway token.
You have been throttled by our API Gateway. We are not intending to implement throttling on this endpoint, but if we detect 3rd parties fetching content at a rate that is causing service issues, we may need to implement some form of throttling. Unless otherwise noted, there will be no throttling for Cars.com or DealerRater consumers to this endpoint.
\nAn unexpected error occurred. If this happens, it is critical that you log the x-correlation-id header in your logs so that we can do root cause analysis on our end and fix whatever went wrong. If this happens, please reach out to our development or product staff, passing along the relevant information (full set of filter and sort options, etc), as well as the returned x-correlation-id header for us to investigate.
This is an optional parameter. If provided, the API will return only the ratings applicable for the given Scope (SalesNew, SalesUsed, or Service). If omitted, the API will return the rating configuration for all three scopes.
\n","type":"text/plain"},"key":"Scope","value":"{{Scope}}"}],"variable":[]}},"response":[],"_postman_id":"b730e7ad-88df-489d-be8b-7cc634e13e7a"}],"id":"f49c523f-2d97-48e0-8c61-1012dd627064","description":"This folder has APIs related to fetching ratings specific to Cars.com dealer reviews.
\n","_postman_id":"f49c523f-2d97-48e0-8c61-1012dd627064"},{"name":"Reviews Collection","item":[{"name":"Fetch Dealer Reviews","id":"8f22abcc-2722-45f4-a909-7c1659f81980","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"description":"The API key you were issued by DealerRater, grating access through our API Gateway.
\n","key":"x-api-key","value":"{{ApiKey}}"}],"url":"https://{{ServicesHost}}/review_v1/dealers/c/{{DealerId}}/consumerreviews","description":"The API will deliver five major pieces of data in the response you'll need to understand with each and every request.
\nThe PagingContext is our standard data structure we use to inform consumers on total result set sizes for queries off this API (you can use it for rendering result set paging links, for example). The PagingContext is specific to anything you might filter on. You can use this object to determine how many pages are in your result set, for example. The StartItem and ItemsPerPage properties merely echo back the values you've passed in with your request, while the TotalItems property tells you how many total items are in this particular result set. To calculate the total number of pages, simply divide TotalItems by ItemsPerPage and round up.
We allow tagging and rating of indivdual dealership employees on dealer reviews only. Each employee record returned will include a these properties: their Id (the unique key you can use to lookup each employee); if they are Active (if this property is false it means their employee profile page should no longer be active); their Picture (fully qualified URI to a picture they've uplaoded); and finally, their FirstName, LastName and Position at the dealership. Each employee record in this list will come to you in the following format:
{\n \"Id\": 23456,\n \"Active\": true,\n \"Picture\": \"https:\\/\\/cdn-user.dealerrater.com\\/images\\/dealer\\/12345\\/employees\\/a55f5935c282.jpg\",\n \"FirstName\": \"John\",\n \"LastName\": \"Doe\",\n \"Position\": \"Internet Manager\"\n }\nWe calculate rollups on a number of different dimensions per-dealer and per-employee. The Rollups section will be split into two different sub-sections: Employees and Dealer, each containing relevant rollups for their respective type.
The review platform includes the concept of a \"Scope\". For dealer reviews, we'll support SalesNew, SalesUsed and Service. There will always be one additional meta-scope relevant to all reviews called Global that matches all scopes combined.
Employee rollups are calculated, as its name implies, per-employee. Each employee rollup can provide you with up to two values: ReviewCount (how many reviews that employee was tagged in) and AverageRating (the employee's average rating). Note that for an employee to be granted a rating at all, they must satisfy a filter condition we encapsulate on the server; if they don't meet the minimum requirements, they will not be granted a rating but the ReviewCount property will still be filled in. To begin with, we are only going to be calculating rollups on the Global scope for employees, so you'll only ever find one rollup per employee. You can find an individual employee's rollup information by indexing their Id in this array and fetching the value in question. Here is an example employee rollup for employee ID 45678, which has enough reviews to be granted a rating:
{\n \"Id\": 45678,\n \"Scopes\": [\n {\n \"Scope\": \"Global\",\n \"ReviewCount\": 28,\n \"AverageRating\": 4.3\n }\n ]\n}\nThis indicates that employee ID 45678 was tagged in 28 reviews with an average rating of 4.3. And another one showing an employee that has not yet met the criteria to be granted a rating:
{\n \"Id\": 7890,\n \"Scopes\": [\n {\n \"Scope\": \"Global\",\n \"ReviewCount\": 4\n }\n ]\n}\nIn this case, employee ID 7890 has a total of 4 reviews, but hasn't yet met the requirements to be given a rating.
Unlike employee rollups, where you may get up to one per employee in the response, for the dealer side of things, you'll only ever get one (you are, after all, fetching reviews by dealership). Dealer-level rollups can include overall review counts and average ratings (as above) but can also include individual per-rating rollups and split by scope (if configured on our backend). For now we won't be calculating them, though they can be added easily enough in the future if required. Also note that for Cars.com, there are no rating rollups outside the global scope. Each rollup includes three properties: Recommend (the percentage of reviews that indicated they recommend the dealer in this scope); ReviewCount (the number of reviews in this scope); and AverageRating (the calculated average rating of all reviews in this scope). We enforce a gating criteria on the rollup calculation such that a dealer must meet a given threshold to be granted an AverageRating and Recommend; if they don't, these values won't be returned. ReviewCount will always be returned, regardless.
{\n \"Scope\": \"Global\",\n \"Recommend\": 95,\n \"ReviewCount\": 7048,\n \"AverageRating\": 4.6\n }\nIn the example above, this hypothetical dealer has a 95% recommendation rating over 7,048 reviews with a 4.6 average rating for all reviews in all scopes. In this case, the dealer does meet the minimum requirements to be granted a rating a recommendation percentage. Here is an example that shows what you can expect to receive for a dealer that does not meet the minimum requirements - you'll get the ReviewCount but not the other two:
{\n \"Scope\": \"Global\",\n \"ReviewCount\": 15\n }\nAnd finally for the meat of the call, the reviews that matched the fetch itself. You will receive a mix of both DealerRater and Cars.com reviews here (which you can determine based on the Source property). You can map a single class to deserialize it and look at only the properties relevant for the given review type.
A Cars.com review will be structured as follows:
\n{\n \"Id\": 1234567,\n \"Source\": \"Cars\",\n \"Scope\": \"SalesNew\",\n \"Recommend\": true,\n \"VehiclePurchased\": true,\n \"UserName\": \"jdoe\",\n \"UserLocation\": \"Waltham, MA\",\n \"Title\": \"Title of the review\",\n \"Body\": \"Main body of the review\",\n \"Date\": \"2019-08-18T09:40:14Z\",\n \"Votes\": {\n \"Up\": 4,\n \"Down\": 0\n },\n \"Ratings\": {\n \"Average\": 4.5,\n \"Overall\": 5,\n \"CustomerService\": 4\n },\n \"EmployeeTags\": [\n {\n \"Id\": 23456,\n \"Rating\": 5\n },\n {\n \"Id\": 37435\n }\n ],\n \"Responses\": [\n {\n \"Id\": 23456,\n \"Body\": \"This is a dealer response on this review.\",\n \"From\": \"Dealer\",\n \"Date\": \"2019-08-18T09:40:14Z\"\n }\n ]\n}\nEach property maps to a question answered by the reviewer on form submission. To be clear:
\nId: Surrogate key for the review, required by other API endpoints.Source: This will be Cars for Cars.com reviews.Scope: The scope selected by the consumer (SalesNew, SalesUsed or Service).Recommend: true or false, based on if the reviewer recommends the dealer.VehiclePurchased: true if the reviewer purchased a vehicle from the dealer.UserName: The name the reviewer wants to be known by.UserLocation: The location the reviewer indicated they live in.Title: Small one-sentence blurb to title the review.Body: The review body itself.Date: The date to show for the review on the public website.Votes: Any up or down votes on the review from consumers.Ratings: Includes one entry for each of the ratings provided by the reviewer and an additional Average that is the calculated average of the individual ratings. Cars.com reviews can be rated on the following properties: Overall, CustomerService, BuyingProcess, QualityOfWork, and Facilities.EmployeeTags: Id and optional per-employee Rating for each employee tagged on the review.Responses: If the dealer has publicly responded to this review, their response(s) will be in this list. Note that for Cars.com reviews, only the Dealer can respond, so From will always be Dealer here.DealerRater reviews are structurally very similar to Cars.com reviews:
\n{\n \"Id\": 234567,\n \"Source\": \"DealerRater\",\n \"Scope\": \"SalesUsed\",\n \"Recommend\": true,\n \"UserName\": \"jdoe\",\n \"Title\": \"Title of the review\",\n \"Body\": \"Main body of the review\",\n \"Date\": \"2019-08-18T09:40:14Z\",\n \"Votes\": {\n \"Up\": 1,\n \"Down\": 0\n },\n \"Ratings\": {\n \"Average\": 5,\n \"Overall\": 5,\n \"Friendliness\": 5\n },\n \"EmployeeTags\": [\n {\n \"Id\": 34567,\n \"Rating\": 5\n },\n {\n \"Id\": 78900\n }\n ],\n \"OtherEmployees\": \"Jane Doe\",\n \"Responses\": [\n {\n \"Body\": \"This is a public dealer response on this review.\",\n \"From\": \"Dealer\",\n \"Date\": \"2019-08-18T09:40:14Z\"\n },\n {\n \"Body\": \"This is a public consumer response on this review.\",\n \"From\": \"Consumer\",\n \"Date\": \"2019-08-18T09:40:14Z\"\n }\n ],\n \"LotShot\": [\n {\n \"PhotoUrl\": \"/images/lotshot/6835aa6f-7a4c-450b-80a1-c2c185958ca6.jpg\",\n \"ThumbnailUrl\": \"/images/lotshot/58735aa6f-7a4c-450b-80a1-c2c185958ca6-th.jpg\",\n \"Date\": \"2019-08-18T09:40:14Z\"\n }\n ]\n}\nEach property maps to a question answered by the reviewer on form submission. To be clear:
\nId: Surrogate key for the review, required by other API endpoints.Source: This will be DealerRater for DealerRater reviews.Scope: The scope selected by the consumer (SalesNew, SalesUsed or Service).Recommend: true or false, based on if the reviewer recommends the dealer.UserName: The name the reviewer wants to be known by.Title: Small one-sentence blurb to title the review.Body: The review body itself.Date: The date to show for the review on the public website.Votes: Any up or down votes on the review from consumers. Note that for DealerRater reviews we'll only be using the up-voting.Ratings: Includes one entry for each of the ratings provided by the reviewer and an additional Average that is the calculated average of the individual ratings. DealerRater reviews can be rated on the following properties: Overall, CustomerService, QualityOfWork, Friendliness, and Price.EmployeeTags: Id and optional per-employee Rating for each employee tagged on the review.OtherEmployees: DealerRater supports a free-form text field that reviewers can type other employee names in they may have worked with, in addition to tagging explicit employees.Responses: If the dealer or consumer has publicly responded to this review, their response(s) will be in this list. Note that for DealerRater reviews, the Dealer or the Reviewer can respond publicly. As such, you'll have either Dealer (the vast majority of the cases) or Reviewer in the From property. If Reviewer is listed in the From property, you can get the name of the user from the UserName property of the review itself.LotShot: Any LotShot photo(s) associated with the review. As of now, we only support a single LotShot photo per review, but in the future we may add more.This section lists off the various mechanisms by which you may request filtering of review content for Cars.com.
\nThe DealerId is passed in as part of the URI itself. You will need to pass in the CCID for the request. We will be validating the CCIDs. Any request to this service with a CCID we do not have record of will result in a 400 Bad Request response.
If you're only after Cars.com reviews, and wish to exclude DealerRater reviews, pass in Cars for the Source query parameter. Likewise for DealerRater, you can pass DealerRater for the Source to just get DealerRater reviews. Note that the dealer-level and employee-level rollups will not change for this filter. Remember those rollups have predefined filter.
Example: /reviews_v1/dealers/c/1234/consumerreviews?Source=Cars
If the end user clicks a review tag on the UI, pass the value in the associated Id property of that tag as the ReviewTag query parameter to this API. The response will ensure that only those reviews that match that tag are returned.\nExample: /reviews_v1/dealers/c/1234/consumerreviews?ReviewTag=FBBAD9837CAB78DA48B3AE4F31D3FAED
It is recommended for performance reasons that you include some form of paging on your reviews page. When requesting a particular page of results from the API, you'll need to pass StartItem (start index is zero and increments as whole integers) and ItemsPerPage (indicates the maximum number of reviews you'd want on any given result set). Below is an example that shows a paged result set, 10 reviews per page, requesting the 3rd page of 10 reviews.\nExample: /reviews_v1/dealers/c/1234/consumerreviews?StartItem=30&ItemsPerPage=10
For rendering dealership reviews that an employee is tagged in (typically done for Employee Profile Pages, or EPPs), simply pass in an EmployeeId query parameter with the ID of the employee in question, and the API will filter the returned list down to just those reviews the for which the employee is tagged. Note that you'll also get the other data back (review tags, dealer rollups, etc) -- none of this is context sensitive. To load the 1st 10 reviews for the EPP for employee 3456, you'd do this:
/reviews_v1/dealers/c/1234/consumerreviews?EmployeeId=3456&StartItem=0&ItemsPerPage=10
\nWe support four sort criteria. The default sort (when not requested) is outlined below. Each value may be passed in as the SortOrder query parameter.
SortOrder value is MostRecent. When sorting by Most Recent, the most recent reviews are returned first, with older reviews later.SortOrder value is HighestRated. When sorting by Highest Rated, we return the reviews with the highest average score first; for reviews with the same average score, a secondary sort by MostRecent is applied.SortOrder value is LowestRated. When sorting by Lowest Rated, we return the reviews with the lowest average score first; for reviews with the same average score, a secondary sort by MostRecent is applied.SortOrder value is MostHelpful. When sorting by Most Helpful, we return the reviews with the highest up-vote count first; for reviews with the same up-vote count, a secondary sort by MostRecent is applied.Requesting the most helpful reviews for dealer 1234 can be done like this (assuming a page count size of 10):
\n/reviews_v1/dealers/c/1234/consumerreviews?StartItem=0&ItemsPerPage=10&SortOrder=MostHelpful\nA hypothetical response to a fetch call to this API that returns only two reviews (one DealerRater and one Cars.com) is shown below. Note that typical response payloads will likely be much larger, I just simplified it down to make it easier to digest in the documentation:
\n{\n \"PagingContext\": {\n \"StartItem\": 0,\n \"ItemsPerPage\": 10,\n \"TotalItems\": 2\n },\n \"Employees\": [\n {\n \"Id\": 45678,\n \"Active\": true,\n \"Picture\": \"https:\\/\\/cdn-user.dealerrater.com\\/images\\/dealer\\/1234\\/employees\\/b75sa935c282.jpg\",\n \"FirstName\": \"John\",\n \"LastName\": \"Doe\",\n \"Position\": \"Sales\"\n }\n ],\n \"Rollups\": {\n \"Employees\": [\n {\n \"Id\": 23456,\n \"Scopes\": [\n {\n \"Scope\": \"Global\",\n \"ReviewCount\": 232,\n \"AverageRating\": 4.5\n }\n ]\n }\n ],\n \"Dealer\": [\n {\n \"Scope\": \"Global\",\n \"Recommend\": 95,\n \"ReviewCount\": 5231,\n \"AverageRating\": 4.6\n } \n ]\n },\n \"ReviewTags\": [\n {\n \"Id\": \"FBBAD9837CDA78DA48B3AE4F31D3FAEC\",\n \"Name\": \"friendly attentive\",\n \"Highlights\": [ \"friendly attentive\" ] \n },\n {\n \"Id\": \"EDB8148C2F757EC226605EA35683D1C2\",\n \"Name\": \"courteous professional\",\n \"Highlights\": [ \"courteous professional\" ] \n }\n ],\n \"Reviews\": [ \n {\n \"Id\": 78901234,\n \"Type\": \"Cars\",\n \"Scope\": \"SalesNew\",\n \"Recommend\": true,\n \"VehiclePurchased\": true,\n \"UserName\": \"Reviewer One\",\n \"Title\": \"Title of the review\",\n \"Body\": \"Body of the review will go here\",\n \"Date\": \"2019-08-18T09:40:14Z\",\n \"Votes\": {\n \"Up\": 4,\n \"Down\": 1\n },\n \"Ratings\": {\n \"Average\": 4.5,\n \"Overall\": 5,\n \"CustomerService\": 4\n },\n \"EmployeeTags\": [\n {\n \"Id\": 7890,\n \"Rating\": 5\n }\n ],\n \"Responses\": [\n {\n \"Body\": \"This is a dealer response on this review.\",\n \"Date\": \"2019-08-18T09:40:14Z\",\n \"From\": \"Dealer\"\n }\n ]\n },\n {\n \"Id\": 456789,\n \"Type\": \"DealerRater\",\n \"Scope\": \"SalesUsed\",\n \"Recommend\": true,\n \"UserName\": \"Reviewer Two\",\n \"Title\": \"Title of the review\",\n \"Body\": \"Body of the review will go here\",\n \"Date\": \"2019-08-18T09:40:14Z\",\n \"Votes\": {\n \"Up\": 1,\n \"Down\": 0\n },\n \"Ratings\": {\n \"Average\": 5,\n \"Overall\": 5,\n \"Friendliness\": 5\n },\n \"EmployeeTags\": [\n {\n \"Id\": 89780\n }\n ],\n \"OtherEmployees\": \"Jane Doe\",\n \"Responses\": [\n {\n \"Body\": \"This is a public dealer response on this review.\",\n \"Date\": \"2019-08-18T09:40:14Z\",\n \"From\": \"Dealer\"\n },\n {\n \"Body\": \"This is a public consumer response on this review.\",\n \"Date\": \"2019-08-18T09:40:14Z\",\n \"From\": \"Consumer\"\n }\n ],\n \"LotShot\": [\n {\n \"PhotoUrl\": \"/images/lotshot/5839ag6f-7a4c-450b-80a1-c2c185958bd6.jpg\",\n \"ThumbnailUrl\": \"/images/lotshot/7939ag6f-7a4c-450b-80a1-c2c185958bd6-th.jpg\",\n \"Date\": \"2019-08-18T09:40:14Z\"\n }\n ]\n }\n ]\n}\nIn order to invoke this API, you will need an API key that is authorized to utilize this service. The API key should be passed in the x-api-key header as part of the request. No Oauth or JWT token will be required.
In the case of a successful fetch, you'll be given a 200 OK response code and the response payload will have the data as defined in this API.
A 400 Bad Request will be returned if, and only if, you invoke this API passing in a Cars.com CCID for which we have no record.
You either did not pass in the x-api-key header correctly or your API key is not authorized for the particular environment you are hitting. Double check the key and try again.
You have been throttled by our API Gateway. The caller should implement a backoff algorithm, slow down, and try again.
\nSomething unexpected happened while we were trying to fetch the reviews. If this occurs, it is critical that you log the x-correlation-id header in your logs so that we can do root cause analysis on our end and fix whatever went wrong. If this happens, please reach out to our development or product staff, passing along the relevant information (full set of filter and sort options, etc), as well as the returned x-correlation-id header for us to investigate.
If supplied, only return reviews matching this source.
\n","type":"text/plain"},"key":"Source","value":"Cars"},{"disabled":true,"description":{"content":"If the user clicks on one of the review tags listed, pass the ID to only return reviews matching that tag. Omit to not filter on tags.
\n","type":"text/plain"},"key":"ReviewTag","value":"FBBAD9837CEA78DA48B3AE4F31D3FAEC"},{"disabled":true,"description":{"content":"The first review to fetch when paging.
\n","type":"text/plain"},"key":"StartItem","value":"0"},{"disabled":true,"description":{"content":"Maximum number of reviews to return per page.
\n","type":"text/plain"},"key":"ItemsPerPage","value":"10"},{"disabled":true,"description":{"content":"When rendering reviews on an employee profile page, you can pass the ID of the employee in here to filter reviews to just that employee.
\n","type":"text/plain"},"key":"EmployeeId","value":"48213"},{"disabled":true,"description":{"content":"One of the enumerated values outlined in the API definition.
\n","type":"text/plain"},"key":"SortOrder","value":"MostRecent"}],"variable":[]}},"response":[],"_postman_id":"8f22abcc-2722-45f4-a909-7c1659f81980"},{"name":"New Dealer Review","id":"ec95d46f-896e-4936-97ca-a41fa7efc717","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"description":"The API key you were issued by DealerRater, grating access through our API Gateway.
\n","key":"x-api-key","value":"{{ApiKey}}"},{"description":"The access token granting permissions to invoke this API endpoint, with permissions as outlined in the specification above.
\n","key":"Authorization","value":"Bearer {{AccessToken}}"},{"description":"Note that you MUST specify the Content-Type header as application/json or the server will not be able to parse your submission.
\n","key":"Content-Type","name":"Content-Type","type":"text","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"Device\": {\n \"Guid\": \"29e7feb9-2469-4d10-aaf8-64d53a80fd97\",\n \"IpAddress\": \"10.1.1.1\"\n },\n \"Dealer\": {\n \"Name\": \"Rogers Hyundai\",\n \"Address\": \"2640 S Michigan Ave\",\n \"City\": \"Chicago\",\n \"State\": \"IL\",\n \"PostalCode\": \"60616\",\n \"Country\": \"US\",\n \"URL\": \"https:\\/\\/www.cars.com\\/dealers\\/147612\\/bozard-ford\\/reviews\\/\",\n \"Latitude\": 0.522342139,\n \"Longitude\": -1.42095632\n },\n \"Title\": \"Many Lincoln vehicles to choose from and were very nice!\",\n \"Body\": \"They were great! I live outside of town so it's not that far and the customer service at Bozard was just phenominal, thank you so much!\",\n \"EmployeeTags\": [\n { \n \"Id\": 8123,\n \"Rating\": 5\n },\n { \n \"Id\": 56781,\n \"Rating\": 5\n },\n { \n \"Id\": 21923\n }\n ],\n \"Ratings\": {\n \"Overall\": 5,\n \"CustomerService\": 5,\n \"BuyingProcess\": 5,\n \"QualityOfWork\": 5,\n \"Facilities\": 5\n },\n \"Scope\": \"SalesNew\",\n \"Recommend\": true,\n \"UserName\": \"farlej2\",\n \"EmailAddress\": \"someone@someaddress.com\",\n \"UserLocation\": \"Waltham, MA\",\n \"VehiclePurchased\": true,\n \"Make\" : {\n \"Id\": 15,\n \"Name\" : \"Ford\"\n },\n \"Model\" : {\n \"Id\": 565,\n \"Name\" : \"Escape\"\n },\n \"EmployeeNames\" : \"Bob Smith\"\n}\n"},"url":"https://{{ServicesHost}}/review_v1/dealers/c/{{DealerId}}/reviews","description":"This API should be invoked if you'd like to create a new Cars.com Dealer Review. The API outlined below requires all the core Cars.com Dealer Review properties, including outlining what is required and what is optional, as well as a bunch of extra data that is required by our moderation platform. All reviews submitted to this endpoint will go live immediately (or almost immediately, remember our read-optimized review store offers an eventual consistency model) with ONE exception: if the review submitted here is detected to have profane content by our moderation algorithms, it will be held in reserve until such time as our moderation staff can look at it. Only at that point will the review either go live (be approved) or be taken down permanently (rejected).
\nIn order for us to accept a review submission, we require a minimal amount of data in order for our moderators to ensure that reviews are real, legitimate, experiences by consumers and not 3rd parties acting on paid behalf of dealers and other stakeholders.
\nThe first piece of data we need is tied to the device the consumer was using to write their review. There are two pieces of data our moderators really like to have, though neither of these is required. The first is called the Device GUID. We request that all submitters of content to our review service somehow tag devices with unique identifiers; in the case of browsers, it can be cookies; in the case of native apps, you can generate one on app install, etc. The second is the Reviewer IP Address. This is exactly as it sounds: the IP address from which the reviewer wrote the review (as close as we can get to their actual IP, even if it is just a NAT IP). The two of these together are used by our moderation team to ensure we don't get the same person submitting reviews in bulk. If you only supply one (or neither) of these values, you risk that our moderation team will reject what might be a valid review, because it will look as though they are all written by the same person. The device information documented here looks like this in the request body of the POST call:
\"Device\": {\n \"Guid\": \"29e7feb9-2469-4d10-aaf8-64d53a80fd97\",\n \"IpAddress\": \"5.5.5.5\"\n}\n\nIf you're writing a dealer review, we need to know what dealer you are writing a review for. Given that Cars and DealerRater do not share a common set of dealer records or objects, the review service (and our moderation platform) requires this information in order for us to properly moderate the reviews. The full set of properties of the dealer includes the name of the dealer, full address, the URL of the review page on the Cars.com website, the latitude and longitude of the dealer and an array mapping the Cars.com dealer ID to the DealerRater dealer ID(s). As part of the submission of this dealer record, we will keep a denormalized set of dealer information up to date in our moderation platform. The dealer information documented here looks like this in the request body of the POST call:
\n\"Dealer\": {\n \"Name\": \"Rogers Hyundai\",\n \"Address\": \"2640 S Michigan Ave\",\n \"City\": \"Chicago\",\n \"State\": \"IL\",\n \"PostalCode\": \"60616\",\n \"Country\": \"US\",\n \"URL\": \"https://www.cars.com/dealers/147612/bozard-ford/reviews/\",\n \"Latitude\": 0.522342139,\n \"Longitude\": -1.42095632\n}\n\nNote that the dealer's surrogate key (the DealerId) is actually included in the URI of the POST call itself.
All Cars.com reviews submitted to the review service must conform to the standard Cars.com review requirements model, including the following properties.
\nThis property is common across all review types in the system and is used for various internal aggregation algorithms for the purpose of scoping reviews of the same type. For the purposes of Cars.com Dealer Reviews, you may pass in one of three values: SalesNew, SalesUsed or Service.
The main body of the review, with a required word count of 25. The word count validation conforms to the following algorithm: split the body of the review on whitespace and count the leftover tokens. If the token count is 25 or more, the validation will succeed. This does mean that a string of \"a a a a a a\" (25 \"a\" words) would pass validation, but the moderation staff would quickly reject it. The body must also have no more than 2,000 words and no more than 4,000 characters. Any review submitted to our service that fails these checks will be rejected with a 400 Bad Request error.
\nThe consumer will need to rate the dealership on a number of different rating categories as defined by the Ratings Collection endpoint. This endpoint is documented elsewhere in the collection and the URI, for reference, is:
\n/review_v1/dealers/c/reviews/ratings\n\nWhat you will be required to do is fetch the rating definitions from this endpoint prior to rendering your review form. The rating categories (the 1-5 star fields the user can supply) are defined here. That API will tell you not only the labels to supply on your UI, but also how to submit the rating values as part of the review form to this service.
\nNote that the ratings are configured per-Scope; when creating a new Dealer Review you must supply a Scope property whose value is SalesNew, SalesUsed or Service. The ratings the user should be presented with are those that are associated with the selected scope that you have retrieved from the ratings API (e.g., if the consumer selects Service, the UI should show the ratings associated with Service; if the user then changes to SalesUsed, the ratings should then reflect the SalesUsed configuration). Ratings with the same Name property value can have their rating selections retained when changing Scopes, if you so choose (some ratings may be shared between different scopes).
For the sake of example, assume that the ratings endpoint above returned the following two categories for the SalesNew scope:
{\n\"Ratings\": [\n {\n \"Name\": \"CustomerService\",\n \"Label\": \"Customer Service\",\n \"Required\": false\n }\n]\n}\n\nYour user input form would need to request one 5-star entry, labelled in your UI as \"Customer Service\".
\nNote that you will need to sort these on your UI. While the ratings endpoint doesn't specifically stipulate a sort order, we are recommending you do the following:
\nLabel alphabeticallyWhen submitting the ratings from the UI to our service, you will need to package up the ratings supplied by the consumer into a ratings object. The property names for each rating are supplied by the Name attribute of each rating object you received from the Rating Collection API call. You should supply any ratings that pertain to the dynamic ratings API as well as an Overall rating. This is the \"main\" rating given to the dealership by the consumer and it is the sole driver for the dealership's overall review score.
\"Ratings\": { \n \"Overall\": 5,\n \"CustomerService\": 4\n}\n\nHere is an example of another reviewer that supplied only the Overall rating:
\n\"Ratings\": { \n \"Overall\": 2\n}\n\nThe API will also ignore any ratings you supply with a null or 0 value, should that make your life easier. The example above, where the consumer just supplied a 2-star Overall rating, can also be submitted as:
\"Ratings\": { \n \"Overall\": 2,\n \"CustomerService\": null\n}\n\nNote: Failure to submit a star rating for all required categories will result in a 400 Bad Request error and your review submission will be rejected.
\nWe provide the ability for consumers to check off individual employees they worked with at the dealership. In order to use this feature, you'll need to have access to our employee data, so you have the correct IDs. Like the normal review-level ratings above, we also provide the ability for consumers to give ratings to the employees they worked with. Unlike the review-level ratings, these are purely optional. If a reviewer decides to rate an employee, the rating value must be in the range of one to five (same as with review-level ratings); omission of a rating can either be submitted to us as a null value or the rating property can be omitted. Here is an example of a review submission where the reviewer worked with three employees (IDs 8123, 56781 and 21923), and they seemed pretty happy with their experience (note that this reviewer did not rate employee 21923):
\"EmployeeTags\": [\n { \n \"Id\": 8123,\n \"Rating\": 5\n },\n { \n \"Id\": 56781,\n \"Rating\": 5\n },\n { \n \"Id\": 21923\n }\n]\n\nFor the submission above for employee 21923, you could have also submitted \"Rating\": null as a valid property as well. Note that, as with the standard ratings above, submitting a rating of 0 will be rejected with a 400 Bad Request. This is invalid:
\"EmployeeTags\": [\n { \n \"Id\": 8123,\n \"Rating\": 0\n }\n]\n\nThis section outlines the other properties, what they mean, and which are required or optional.
\ntrue or false label.true or false label.Make: Id and Name of the vehicle make the review experience pertains toModel: Id and Name of the vehicle model the review experience pertains toIn order to post a new review to the review service, you will need to provide a JWT access token in the Authorization header as an Authorization: Bearer [YOUR_TOKEN] value. You must be granted the rvw_cars permission in order to invoke the API. Note: We are eyeing the possibility of further locking down these review POSTs based on Dealer ID as well, but the mechanism for which that will be done builds on what we're doing here and is fully backwards compatible. For now, just having the rvw_cars permission in your JWT token will be sufficient.
Here is a sample request body outlining all the properties outlined in the overview section in one sample review submission. Hopefully this will glue all the pieces together for you:
\n{\n \"Device\": {\n \"Guid\": \"29e7feb9-2469-4d10-aaf8-64d53a80fd97\",\n \"IpAddress\": \"10.1.1.1\"\n },\n \"Dealer\": {\n \"Name\": \"Rogers Hyundai\",\n \"Address\": \"2640 S Michigan Ave\",\n \"City\": \"Chicago\",\n \"State\": \"IL\",\n \"PostalCode\": \"60616\",\n \"Country\": \"US\",\n \"URL\": \"https:\\/\\/www.cars.com\\/dealers\\/147612\\/bozard-ford\\/reviews\\/\",\n \"Latitude\": 0.522342139,\n \"Longitude\": -1.42095632\n },\n \"Scope\": \"SalesNew\",\n \"Body\": \"They were great! I live outside of town so it's not that far and the customer service at Bozard was just phenominal, thank you so much!\",\n \"EmployeeTags\": [\n { \n \"Id\": 8123,\n \"Rating\": 5\n },\n { \n \"Id\": 56781,\n \"Rating\": 5\n },\n { \n \"Id\": 21923\n }\n ],\n \"Ratings\": {\n \"Overall\": 5,\n \"CustomerService\": 5\n },\n \"Recommend\": true,\n \"UserName\": \"farlej2\",\n \"EmailAddress\": \"someone@someaddress.com\",\n \"UserLocation\": \"Waltham, MA\",\n \"VehiclePurchased\": true\n}\n\nYou can expect one of several response codes.
\nIn the event of a successful submission of a review to our platform, you can expect to receive a 201 Created HTTP response code. In the body of the payload you'll find the submitted review echoed back to you, along with a new Id property identifying the surrogate key of the new review in the review platform. Please note that due to how our moderation system works, if we detect that the text contains profane content, it might be scrubbed out during our moderation process (e.g., the review title, text, and other user-entered data could be returned at a later date in a slightly different format to remove the profane content). An example response would look something like this for the request body posted above (note that the response will exclude all information provided for the sole purpose of moderation - e.g., we will not echo back the Dealer, Device or Email Address of the consumer):
{\n \"Id\": 23589723,\n \"Device\": {\n \"Guid\": \"29e7feb9-2469-4d10-aaf8-64d53a80fd97\",\n \"IpAddress\": \"10.1.1.1\"\n },\n \"Dealer\": {\n \"Name\": \"Rogers Hyundai\",\n \"Address\": \"2640 S Michigan Ave\",\n \"City\": \"Chicago\",\n \"State\": \"IL\",\n \"PostalCode\": \"60616\",\n \"Country\": \"US\",\n \"URL\": \"https:\\/\\/www.cars.com\\/dealers\\/147612\\/bozard-ford\\/reviews\\/\",\n \"Latitude\": 0.522342139,\n \"Longitude\": -1.42095632\n },\n \"Scope\": \"SalesNew\",\n \"Body\": \"They were great! I live outside of town so it's not that far and the customer service at Bozard was just phenominal, thank you so much!\",\n \"EmployeeTags\": [\n { \n \"Id\": 8123,\n \"Rating\": 5\n },\n { \n \"Id\": 56781,\n \"Rating\": 5\n },\n { \n \"Id\": 21923\n }\n ],\n \"Ratings\": {\n \"Overall\": 5,\n \"CustomerService\": 5\n },\n \"Recommend\": true,\n \"UserName\": \"farlej2\",\n \"UserLocation\": \"Waltham, MA\",\n \"VehiclePurchased\": true\n}\n\nIn the event of a malformed payload, if the server is unable to decipher what you have submitted, if you submit a DealerId as the Cars.com CCID that we have no record of, or if your submission does not for some means pass our validation rules, you will receive a 400 Bad Request response code. The response body will have some details as to what caused the 400 Bad Request error. Fix your submission and try again.
There was an error with your JWT token.
\nThere was an error with your x-api-key API Gateway token.
\nYou have been throttled by our API Gateway. We are not intending to implement throttling on this endpoint, but if we detect 3rd parties submitting content at a rate that is causing service issues, we may need to implement some form of throttling. Unless otherwise noted, there will be no throttling for Cars.com or DealerRater consumers to this endpoint.
\nSomething unexpected happened during the processing of your review submission. If this occurs, it is critical that you log the x-correlation-id header in your logs so that we can do root cause analysis on our end and fix whatever went wrong. If this happens, please reach out to our development or product staff, passing along the relevant information (full request body if you have it) as well as the returned x-correlation-id header for us to investigate.
This folder contains APIs specific to the Reviews collection itself.
\n","_postman_id":"270aabb3-2cf9-4fdf-a6f4-45fd58b25ad7"},{"name":"Review Entity","item":[{"name":"Review Responses","item":[{"name":"New Dealer Review Response","id":"04ff10c2-1c47-40a5-9d5b-46a0cfe69043","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"description":"The API key you were issued by DealerRater, granting access through our API Gateway.
\n","key":"x-api-key","value":"{{ApiKey}}"},{"description":"The access token granting permissions to invoke this API endpoint, with permissions as outlined in the specification above.
\n","key":"Authorization","value":"Bearer {{AccessToken}}"},{"description":"Note that you MUST specify the Content-Type header as application/json or the server will not be able to parse your submission.
\n","key":"Content-Type","name":"Content-Type","type":"text","value":"application/json"}],"body":{"mode":"raw","raw":"{\r\n \"Body\": \"Thank you for the kind words, we are so happy you had a great experience! If we can serve your needs at any point in the future, please don't hesitate to give us a call!\"\r\n}"},"url":"https://{{ServicesHost}}/review_v1/dealers/c/{{DealerId}}/reviews/{{ReviewId}}/responses","description":"This API should be invoked if you'd like to create a new response on an existing Cars.com Dealer Review. Responses are the sole mechanism a dealer has to communicate back to a consumer on a review that the consumer left - perhaps to thank them for a nice review, or to ask if there is anything they might do to assist in the case of a bad experience or negative review. For now, there will be a one response maximum per review. Attempting to create a new response on a review that already has a response will yield an error.
\nThe Dealer Response must include a Body property that is non-null and contains at least one, but not more than 25K (25,600) characters. There can be at most a single response on a Cars.com dealer review. Attempting to create a response on a review that already has one will yield an error (see below). If a review already has a response and you want to create a new one, you must either use the PUT API to update, or first use the DELETE API then use this one to create a new response. All Cars.com dealer responses are, by default, publicly visible.
In order to post a new response to the review service, you will need to provide a JWT access token in the Authorization header as an Authorization: Bearer [YOUR_TOKEN] value. The access token should have been generated using the Security API as described in this documentation with the CCID of the dealer in the scope of the request, and the access token should not have expired. An access token is tied to a dealer, and should be generated separately for each dealer.
\nHere is a sample request body outlining how to create a new response on a review. Note that the ReviewId (and DealerId that owns the review) that stipulate which review is receiving the response, are included in the URI (in the case below, a made-up dealer ID of 2345 and review ID of 5678 are used).
\nPOST /review_v1/dealers/c/2345/reviews/5678/responses\n{\n \"Body\": \"Thank you for the kind words, we are so happy you had a great experience! If we can serve your needs at any point in the future, please don't hesitate to give us a call!\"\n}\n\nYou can expect one of several response codes.
\nIn the event of a successful submission of a response to our platform, you can expect to receive a 201 Created HTTP response code.
\n{\n \"Id\": 34567789,\n \"Body\": \"Thank you for the kind words, we are so happy you had a great experience! If we can serve your needs at any point in the future, please don't hesitate to give us a call!\",\n \"DateEntered\": \"2020-11-18T09:40:14Z\",\n \"DateUpdated\": \"2020-11-18T09:40:14Z\"\n}\n\nThe body of the response also includes a few extra properties, should you need them for whatever:
\nId: The surrogate key of the response.
Body: The response body, verbatim and echoed back to the caller (this will be identical to what you POSTed).
DateEntered: When the response was created (timestamp of this call, essentially).
DateUpdated: When the response was last updated (since this is a new response, it will be the same as DateEntered).
In the event of a malformed payload, if the server is unable to decipher what you have submitted, or if your submission does not for some means pass our validation rules (if the Body was not provided, or was too large), you will receive a 400 Bad Request response code. The response body will have some details as to what caused the 400 Bad Request error. Fix your submission and try again.
You are not authorized to invoke this endpoint. This might be that your API key and/or submitted JWT bearer token do not posses the required privileges to invoke this endpoint or that your JWT token is valid but expired. If you expect to have privileges to invoke this API, you'll need to verify that the required headers are present, have the correct name, and are being submitted per the requirements laid out in this specification.
\nWe were unable to find the given Review ID to add the response to.
\nSomething unexpected happened during the processing of your review submission. If this occurs, it is critical that you log the x-correlation-id header in your logs so that we can do root cause analysis on our end and fix whatever went wrong. If this happens, please reach out to our development or product staff, passing along the relevant information (full request body if you have it) as well as the returned x-correlation-id header for us to investigate.
The API key you were issued by DealerRater, grating access through our API Gateway.
\n"},{"key":"Authorization","value":"Bearer {{AccessToken}}","description":"The access token granting permissions to invoke this API endpoint, with permissions as outlined in the specification above.
\n"},{"key":"Content-Type","value":"application/json","description":"Note that you MUST specify the Content-Type header as application/json or the server will not be able to parse your submission.
\n","type":"text"}],"body":{"mode":"raw","raw":"{\n \"Body\": \"This is an update. Thank you for the kind words, we are so happy you had a great experience! If we can serve your needs at any point in the future, please don't hesitate to give us a call!\"\n}"},"url":"https://{{ServicesHost}}/review_v1/dealers/c/{{DealerId}}/reviews/{{ReviewId}}/responses/{{ResponseId}}","description":"This API should be invoked if you'd like to update an existing response on a Cars.com Dealer Review.
\nThe Dealer Response must include a Body property that is non-null and contains at least one, but not more than 25K (25,600) characters.
In order to update an existing response in the review service, you will need to provide a JWT access token in the Authorization header as an Authorization: Bearer [YOUR_TOKEN] value. The access token should have been generated using the Security API as described in this documentation with the CCID of the dealer in the scope of the request, and the access token should not have expired. An access token is tied to a dealer, and should be generated separately for each dealer.
\nHere is a sample request body outlining how to update an existing response on a review. Note that the ReviewId (and DealerId that owns the review) that stipulate which review is receiving the response, are included in the URI (in the case below, a made-up dealer ID of 23456 and review ID of 56789, and we are updating response ID 843281).
\nPUT /review_v1/dealers/c/23456/reviews/56789/responses/843281\n{\n \"Body\": \"Thank you for the kind words, we are so happy you had a great experience! If we can serve your needs at any point in the future, please don't hesitate to give us a call!\"\n}\n\nYou can expect one of several response codes.
\nIn the event of a successful submission of an updated response to our platform, you can expect to receive a 200 OK HTTP response code. In the body of the payload you'll find the submitted response echoed back to you, along with a few extra properties (same as those you get when creating a new response):
\n{\n \"Id\": 23589723,\n \"Body\": \"Thank you for the kind words, we are so happy you had a great experience! If we can serve your needs at any point in the future, please don't hesitate to give us a call!\",\n \"DateEntered\": \"2020-11-18T09:40:14Z\",\n \"DateUpdated\": \"2020-11-18T09:40:14Z\"\n}\n\nThe body of the response also includes a few extra properties, should you need them for whatever:
\nId: The surrogate key of the response.
Body: The response body, verbatim and echoed back to the caller (this will be identical to what you sent to the server).
DateEntered: When the response was originally created.
DateUpdated: This will be updated to the current time, as the response was changed.
In the event of a malformed payload, if the server is unable to decipher what you have submitted, or if your submission does not for some means pass our validation rules (if the Body was not provided, or was too large), you will receive a 400 Bad Request response code. The response body will have some details as to what caused the 400 Bad Request error. Fix your submission and try again.
You are not authorized to invoke this endpoint. This might be that your API key and/or submitted JWT bearer token do not posses the required privileges to invoke this endpoint or that your JWT token is valid but expired. If you expect to have privileges to invoke this API, you'll need to verify that the required headers are present, have the correct name, and are being submitted per the requirements laid out in this specification.
\nThe given response ID could not be found to be updated.
\nYou have been throttled by our API Gateway. The caller should implement a backoff algorithm, slow down, and try again.
\nSomething unexpected happened during the processing of your review submission. If this occurs, it is critical that you log the x-correlation-id header in your logs so that we can do root cause analysis on our end and fix whatever went wrong. If this happens, please reach out to our development or product staff, passing along the relevant information (full request body if you have it) as well as the returned x-correlation-id header for us to investigate.
The API key you were issued by DealerRater, grating access through our API Gateway.
\n"},{"key":"Authorization","value":"Bearer {{AccessToken}}","description":"The access token granting permissions to invoke this API endpoint, with permissions as outlined in the specification above.
\n"}],"url":"https://{{ServicesHost}}/review_v1/dealers/c/{{DealerId}}/reviews/{{ReviewId}}/responses","description":"This API should be invoked if you'd like to delete an existing response on a Cars.com Dealer Review.
\nIn order to delete an existing response in the review service, you will need to provide a JWT access token in the Authorization header as an Authorization: Bearer [YOUR_TOKEN] value. The access token should have been generated using the Security API as described in this documentation with the CCID of the dealer in the scope of the request, and the access token should not have expired. An access token is tied to a dealer, and should be generated separately for each dealer.
\nHere is a sample request body outlining how to delete an existing response on a review. Note that the ReviewId (and DealerId that owns the review), along with the ResponseId you are requesting to be deleted, are included in the URI .
\nDELETE /review_v1/dealers/c/23456/reviews/7890/responses/56789\n\nYou can expect one of several response codes.
\nIn the event of a successful deletion of a response in the system, you'll receive a 200 OK response. The response body itself will be empty.
\nYou are not authorized to invoke this endpoint. This might be that your API key and/or submitted JWT bearer token do not posses the required privileges to invoke this endpoint or that your JWT token is valid but expired. If you expect to have privileges to invoke this API, you'll need to verify that the required headers are present, have the correct name, and are being submitted per the requirements laid out in this specification.
\nThe given response ID could not be found to be deleted.
\nYou have been throttled by our API Gateway. The caller should implement a backoff algorithm, slow down, and try again.
\nSomething unexpected happened during the processing of your review submission. If this occurs, it is critical that you log the x-correlation-id header in your logs so that we can do root cause analysis on our end and fix whatever went wrong. If this happens, please reach out to our development or product staff, passing along the relevant information (full request body if you have it) as well as the returned x-correlation-id header for us to investigate.
This folder contains various APIs that can be used to manage individual dealer responses on a particular Cars.com dealer review.
\n","event":[{"listen":"prerequest","script":{"type":"text/javascript","exec":[""],"id":"18d77af7-d758-47b7-a987-a51375be45d2"}},{"listen":"test","script":{"type":"text/javascript","exec":[""],"id":"629db9cd-8c7e-43ef-b074-6f58ac2a6304"}}],"_postman_id":"c6f38b66-1f11-4e1b-a93c-cc2222e6bbaa"}],"id":"05d8cedc-8263-4d84-9803-f365e9956bfe","description":"Folders and API calls in this folder are applicable to individual Cars.com reviews.
\n","_postman_id":"05d8cedc-8263-4d84-9803-f365e9956bfe"}],"id":"478a59f1-05e5-4cc9-8eb3-02222d22d1e6","description":"This folder contains the APIs specific to Cars.com Dealer Reviews.
\n","_postman_id":"478a59f1-05e5-4cc9-8eb3-02222d22d1e6"},{"name":"DealerRater","item":[{"name":"Rollups Collection","item":[{"name":"Fetch Dealer Rollups (GET)","id":"b61ad225-2ee9-4fff-9500-adea2c3f33bc","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"description":"The API key you were issued by DealerRater, grating access through our API Gateway.
\n","key":"x-api-key","value":"{{ApiKey}}"}],"url":"https://{{ServicesHost}}/review_v1/dealers/d/rollups?i=2259","description":"Use this API to fetch dealer (and, if needed, employee) rollups on any webpage on your site include high-capacity and/or high-traffic pages. The implementation is designed to fetch and return the data in as low-latency a manner as possible utilizing caching to the best of our ability.
\nA sample rollup you'll get for each dealer is listed below. Note that all rollups for a given dealer will be included in a JSON object under that dealer's ID. For a more complete understanding of the values in the rollups, please refer to the Fetch Dealer Reviews (GET) API. There can be a maximum of two of these arrays, one that includes dealer rollups and one (if requested - see below) that would include the employee rollups.
\n{\n \"Id\": 10,\n \"Rollups\": [\n {\n \"Scope\": \"Global\",\n \"Recommend\": 95,\n \"ReviewCount\": 7048,\n \"AverageRating\": 4.6\n }\n ]\n}\nWhen submitting a request to this endpoint, you must provide at least one dealer ID to load rollups for (but it can be up to 100). Each dealer ID should be given as a single query string i on the query line. If you are fetching rollups for dealer IDs 50, 60 and 70 the fetch would look like this:
/reviews_v1/dealers/c/rollups?i=50&i=60&i=70\nYou can also supply a Scope parameter which will only return rollups for the provided scope. If not given, Global is assumed and you will get rollups back for all scopes.
/reviews_v1/dealers/c/rollups?i=50&i=60&i=70&Scope=Service\nIf you also want to request employee rollups be returned for all the given dealer IDs you passed in, you need to add an e=true parameter, as below. Note that (as of right now) there is no link in the returned JSON that will tell you what employee(s) belong to what dealer(s); the response itself will include the specific dealer ID(s) and employee ID(s), but if you need to know what IDs map to what, you'll need to look elsewhere.
/reviews_v1/dealers/c/rollups?e=true&i=50&i=60&i=70\nA hypothetical response to a fetch call to this API for which you fetched rollups for a single dealer with ID 10 where you also requested employee rollups might look like this:
\n{\n \"Dealers\": [\n {\n \"Id\": 10,\n \"Rollups\": [\n {\n \"Scope\": \"Global\",\n \"Recommend\": 94.2,\n \"ReviewCount\": 2160,\n \"AverageRating\": 4.7\n }\n ]\n }\n ],\n \"Employees\": [\n {\n \"Id\": 57,\n \"Rollups\": [\n {\n \"ReviewCount\": 10,\n \"AverageRating\": 4.9\n }\n ]\n }\n ]\n}\nIn order to invoke this API, you will need an API key that is authorized to utilize this service. The API key should be passed in the x-api-key header as part of the request. No Oauth or JWT token will be required, to keep latencies down.
In the case of a successful fetch, you'll be given a 200 OK resopnse code and the response payload will have the data as defined in this API.
A 400 Bad Request will be returned if, and only if, you invoke this API and pass in no dealer IDs or if you attempt to load more than the maximum allowable in a single request, which at the time of release was 100.
There was an error with your JWT token.
\nThere was an error with your x-api-key API Gateway token.
\nYou have been throttled by our API Gateway. We are not intending to implement throttling on this endpoint, but if we detect 3rd parties fetching content at a rate that is causing service issues, we may need to implement some form of throttling. Unless otherwise noted, there will be no throttling for Cars.com or DealerRater consumers to this endpoint.
\nSomething unexpected happened while we were trying to fetch the reviews. If this occurs, it is critical that you log the x-correlation-id header in your logs so that we can do root cause analysis on our end and fix whatever went wrong. If this happens, please reach out to our development or product staff, passing along the relevant information (full set of filter and sort options, etc), as well as the returned x-correlation-id header for us to investigate.
We will be implementing very heavy caching on this API, and it will involve an eventual-consistency data model. You can make the cache work better for you by keeping the total number of permutations of these values as low as possible; for example, if you fetch rollups for a set of dealer IDs, always sort the dealer IDs the same way to ensure that the cache key will match with all subsequent requests.
\n","urlObject":{"protocol":"https","path":["review_v1","dealers","d","rollups"],"host":["{{ServicesHost}}"],"query":[{"disabled":true,"description":{"content":"If given as value true, the API will return employee rollups for the dealers requested. If not provided, you will just get dealer rollups.
The set of dealer IDs to receive rollups for. Each dealer ID should be submitted as part of its own unique i parameter.
If provided, allows you to filter and only fetch one particular scope. If not given, defaults to Global which returns rollups for all scopes.
\n","type":"text/plain"},"key":"Scope","value":"Service"},{"disabled":true,"description":{"content":"Identifies the precision of the rollups you want back (how many decimal places). Default value is 1 (e.g. 4.1, 5.0, etc). You can specify any number between 0 and 5.
\n","type":"text/plain"},"key":"p","value":"1"}],"variable":[]}},"response":[],"_postman_id":"b61ad225-2ee9-4fff-9500-adea2c3f33bc"}],"id":"8798292e-d17c-439b-a0be-3ff59706d538","description":"APIs in this folder relate directly to dealer rollups.
\n","_postman_id":"8798292e-d17c-439b-a0be-3ff59706d538"},{"name":"Reviews Collection","item":[{"name":"Fetch Dealer Reviews","id":"73397584-2f25-43d0-9997-c8765500592a","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"description":"The API key you were issued by DealerRater, grating access through our API Gateway.
\n","key":"x-api-key","value":"{{ApiKey}}"}],"url":"https://{{ServicesHost}}/review_v1/dealers/d/{{DealerId}}/consumerreviews","description":"This API should be your starting point if you are planning on implementing a high-capacity, high-traffic, web page on which you want to render DealerRater review data. Our entire goal on coding this API was to provide all the relevant review information in one request/response pair to this service. The service offers an eventual consistency model with heavy caching built in to deliver the lowest latency and highest throughput we possibly can.
\nThe API will deliver five major pieces of data in the response you'll need to understand with each and every request.
\nThe PagingContext is our standard data structure we use to inform consumers on total result set sizes for queries off this API (you can use it for rendering result set paging links, for example). Unlike the rollup information (described in detail below), the PagingContext is specific to anything you might filter on, including things like Review Tags (also detailed below). You can use this object to determine how many pages are in your result set, for example. The StartItem and ItemsPerPage properties merely echo back the values you've passed in with your request, while the TotalItems property tells you how many total items are in this particular result set. To calculate the total number of pages, simply divide TotalItems by ItemsPerPage and round up.
We allow tagging and rating of individual dealership employees on dealer reviews only. As part of display reviews on consumer websites, we also like to show small blocks of informational text about each employee that was rated (typically their photo, first and last name, position at the dealership, etc). In order to make the fetch call as fast as possible, we decided to extract the denormalized employee data into a separate section. Each employee record returned will include a few properties: their Id (the unique key you can use to lookup each employee); if they are Active (if this property is false it means their employee profile page should no longer be active); their Picture (fully qualified URI to a picture they've uplaoded); and finally, their FirstName, LastName and Position at the dealership. Each employee record in this list will come to you in the following format:
{\n \"Id\": 238423,\n \"Active\": true,\n \"Picture\": \"https:\\/\\/cdn-user.dealerrater.com\\/images\\/dealer\\/19361\\/employees\\/b55f5935c282.jpg\",\n \"FirstName\": \"Joe\",\n \"LastName\": \"Schmo\",\n \"Position\": \"Internet Manager\"\n }\n\nAll reviews when submitted by a consumer will have one or more star rating assignments given to various ratings (e.g., Price, Customer Service, Comfort, etc). These ratings are now subject to change over time, and you will need a way to represent the categories in your UI with user-friendly labels as well as have a mechanism to sort them in a consistent manner. The data found here will help you do that.
\nBefore going into the specifics on what is in this array, note that all reviews will be given a static, hardcoded, Average property in its Ratings object. This property will always be present in the ratings returned and should be used if you want to show a star average for the review overall, instead of the per-rating assignments. The calculation for this field is internal to our systems. To reiterate, when showing the rating average for the review as a whole, use the Average property, which will always be present. Many reviews will also have an Overall property in the Ratings section - do not confuse this with the Average. Overall is a dynamic category and is subject to change!
As for what you can find in this array, each JSON object has a very simple form, in the following format:
\n{\n\"Name\": \"CustomerService\",\n\"Label\": \"Customer Service\",\n\"Required\": false\n}\n\nThe Name property is what you will use as a key to lookup this rating type in the Ratings section of a given review. For example, a consumer may have rated a dealer on their CustomerService category. In order to display the label for that category, you would look in this array for the object with a Name of CustomerService and take the Label property for use in your UI.
For sorting, we highly recommend the following:
\nRequired is true) and optional ratings (where Required is false)This will ensure that all reviews have the most prominent ratings at the top, and that all reviews in your UI have a consistent sort order.
\nThis section will likely be the most complicated to understand (though not too bad). As part of our backend processes, we calculate rollups on a number of different dimensions per-dealer and per-employee. We will be building as generic of a \"rollup engine\" as we can, so hopefully these can be expanded and/or tuned as requirements change. Long story short, the Rollups section will be split into two different sub-sections: Employees and Dealer, each containing relevant rollups for their respective type.
The review platform includes the concept of a \"Scope\" that allows us to slice and dice reviews along this one dimension. For dealer reviews (to start), we'll support SalesNew, SalesUsed and Service. There will always be one additional meta-scope relevant to all reviews called Global that matches all scopes combined. The rollup engine makes heavy use of configuration data and scopes in the backend for calculating various rollups.
Employee rollups are calculated, as its name implies, per-employee. Each employee rollup can provide you with up to two values: ReviewCount (how many reviews that employee was tagged in) and AverageRating (the employee's average rating). Note that for an employee to be granted a rating at all, they must satisfy a filter condition we encapsulate on the server; if they don't meet the minimum requirements, they will not be granted a rating but the ReviewCount property will still be filled in. To begin with, we are only going to be calculating rollups on the Global scope for employees, so you'll only ever find one rollup per employee. You can find an individual employee's rollup information by indexing their Id in this array and fetching the value in question. Here is an example employee rollup for employee ID 89213, which has enough reviews to be granted a rating:
{\n \"Id\": 89213,\n \"Scopes\": [\n {\n \"Scope\": \"Global\",\n \"ReviewCount\": 28,\n \"AverageRating\": 4.3\n }\n ]\n}\n\nThis indicates that employee ID 89213 was tagged in 28 reviews with an average rating of 4.3. And another one showing an employee that has not yet met the criteria to be granted a rating:
{\n \"Id\": 14361,\n \"Scopes\": [\n {\n \"Scope\": \"Global\",\n \"ReviewCount\": 4\n }\n ]\n}\n\nIn this case, employee ID 14361 has a total of 4 reviews, but hasn't yet met the requirements to be given a rating.
Unlike employee rollups, where you may get up to one per employee in the response, for the dealer side of things, you'll only ever get one (you are, after all, fetching reviews by dealership). Dealer-level rollups can include overall review counts and average ratings (as above) but can also include individual per-rating rollups and split by scope (if configured on our backend). Each rollup includes three properties: Recommend (the percentage of reviews that indicated they recommend the dealer in this scope); ReviewCount (the number of reviews in this scope); and AverageRating (the calculated average rating of all reviews in this scope). We enforce a gating criteria on the rollup calculation such that a dealer must meet a given threshold to be granted an AverageRating and Recommend; if they don't, these values won't be returned. ReviewCount will always be returned, regardless.
{\n \"Scope\": \"Global\",\n \"Recommend\": 95,\n \"ReviewCount\": 7048,\n \"AverageRating\": 4.6\n }\n\nIn the example above, this hypothetical dealer has a 95% recommendation rating over 7,048 reviews with a 4.6 average rating for all reviews in all scopes. In this case, the dealer does meet the minimum requirements to be granted a rating a recommendation percentage. Here is an example that shows what you can expect to receive for a dealer that does not meet the minimum requirements - you'll get the ReviewCount but not the other two:
{\n \"Scope\": \"Global\",\n \"ReviewCount\": 15\n }\n\nAnd finally for the meat of the call, the reviews that matched the fetch itself. You will receive only DealerRater review content from this API.
\nDealerRater reviews are structurally very similar to Cars.com reviews:
\n{\n \"Id\": 2821331,\n \"Source\": \"DealerRater\",\n \"Scope\": \"SalesUsed\",\n \"Recommend\": true,\n \"UserName\": \"farlej2\",\n \"Verified\": true,\n \"Title\": \"Title of the review\",\n \"Body\": \"Main body of the review\",\n \"Date\": \"2019-08-18T09:40:14Z\",\n \"Votes\": {\n \"Up\": 1,\n \"Down\": 0\n },\n \"Ratings\": {\n \"Average\": 5,\n \"Overall\": 5,\n \"Friendliness\": 5\n },\n \"Make\": {\n \"Id\": 46,\n \"Slug\": \"toyota\",\n \"Name\": \"Toyota\"\n },\n \"Model\": {\n \"Id\": 1536,\n \"Slug\": \"corona\",\n \"Name\": \"Corona\"\n },\n \"EmployeeTags\": [\n {\n \"Id\": 32235,\n \"Rating\": 5\n },\n {\n \"Id\": 79765\n }\n ],\n \"OtherEmployees\": \"Jane Doe\",\n \"Responses\": [\n {\n \"Body\": \"This is a public dealer response on this review.\",\n \"From\": \"Dealer\",\n \"Date\": \"2019-08-18T09:40:14Z\"\n },\n {\n \"Body\": \"This is a public consumer response on this review.\",\n \"From\": \"Consumer\",\n \"Date\": \"2019-08-18T09:40:14Z\"\n }\n ],\n \"LotShot\": [\n {\n \"PhotoUrl\": \"/images/lotshot/5939aa6f-7a4c-450b-80a1-c2c185958bd6.jpg\",\n \"ThumbnailUrl\": \"/images/lotshot/5939aa6f-7a4c-450b-80a1-c2c185958bd6-th.jpg\",\n \"Date\": \"2019-08-18T09:40:14Z\"\n }\n ]\n}\n\nFairly simple. Each property maps to a question answered by the reviewer on form submission. To be clear:
\nId: Surrogate key for the review, required by other API endpoints.Source: This will be DealerRater for DealerRater reviews.Scope: The scope selected by the consumer (SalesNew, SalesUsed or Service).Recommend: true or false, based on if the reviewer recommends the dealer.UserName: The name the reviewer wants to be known by.Verified: If true, this review has been tied to the dealer's DMS system and represents a verified sale on an actual vehicle, similar to how Amazon does \"Verified Purchase\" reviews.Title: Small one-sentence blurb to title the review.Body: The review body itself.Date: The date to show for the review on the public website.Votes: Any up or down votes on the review from consumers. Note that for DealerRater reviews we'll likely only be using the up-voting.Ratings: Includes one entry for each of the ratings provided by the reviewer and an additional Average that is the calculated average of the individual ratings. When showing the per-review overall Average, use the Average field. The rest of the categories in this object are dynamic; the labels for them can be found in the Ratings array outlined above. Note that you will ALWAYS get an Average on each review and this property can be treated as being static or hardcoded and is not subject to change.Make: The make that was selected when the consumer wrote the review. Almost all of our reviews should have this property set, with the exception of some VERY old ones.Model: The vehicle model that was selected when the consumer wrote the review. This is a newer property and will only be present on reviews written after mid-2022 or so.EmployeeTags: Id and optional per-employee Rating for each employee tagged on the review.OtherEmployees: DealerRater supports a free-form text field that reviewers can type other employee names in they may have worked with, in addition to tagging explicit employees.Responses: If the dealer or consumer has publicly responded to this review, their response(s) will be in this list. Note that for DealerRater reviews, the Dealer or the Reviewer can respond publicly. As such, you'll have either Dealer (the vast majority of the cases) or Reviewer in the From property. If Reviewer is listed in the From property, you can get the name of the user from the UserName property of the review itself.LotShot: Any LotShot photo(s) associated with the review. As of now, we only support a single LotShot photo per review, but in the future we may add more. In order to build some expandability into the API, we've left this an array (just in case). For now, you can just assume there is one object here.This section lists off the various mechanisms by which you may request filtering of review content for Cars.com.
\nThe DealerId is passed in as part of the URI itself. You will need to pass in the CCID for the request. We will be validating the CCIDs against a table we keep up to date from SalesForce. Any request to this service with a CCID we do not have record of will result in a 400 Bad Request response.
It is recommended for performance reasons that you include some form of paging on your reviews page. When requesting a particular page of results from the API, you'll need to pass StartItem (start index is zero and increments as whole integers) and ItemsPerPage (indicates the maximum number of reviews you'd want on any given result set). Here is an example that shows a paged result set, 10 reviews per page, requesting the 3rd page of 10 reviews:
/reviews_v1/dealers/c/3282/consumerreviews?StartItem=30&ItemsPerPage=10\n\nFor rendering dealership reviews that an employee is tagged in (typically done for Employee Profile Pages, or EPPs), simply pass in an EmployeeId query parameter with the ID of the employee in question, and the API will filter the returned list down to just those reviews the for which the employee is tagged. Note that you'll also get the other data back (review tags, dealer rollups, etc) -- none of this is context sensitive. We may end up doing that at some point, but don't have the time as part of phase one. For now, when you call the API with an EmployeeId just ignore those pieces. To load the 1st 10 reviews for the EPP for employee 34812, you'd do this:
/reviews_v1/dealers/c/3282/consumerreviews?EmployeeId=34812&StartItem=0&ItemsPerPage=10\n\nWe will support four sort criteria at launch. The default sort (when not requested) is outlined below. Each value may be passed in as the SortOrder query parameter.
SortOrder value is MostRecent. When sorting by Most Recent, the most recent reviews are returned first, with older reviews later.SortOrder value is HighestRated. When sorting by Highest Rated, we return the reviews with the highest average score first; for reviews with the same average score, a secondary sort by MostRecent is applied.SortOrder value is LowestRated. When sorting by Lowest Rated, we return the reviews with the lowest average score first; for reviews with the same average score, a secondary sort by MostRecent is applied.SortOrder value is MostHelpful. When sorting by Most Helpful, we return the reviews with the highest up-vote count first; for reviews with the same up-vote count, a secondary sort by MostRecent is applied.Requesting the most helpful reviews for dealer 3282 can be done like this (assuming a page count size of 10):
\n/reviews_v1/dealers/c/3282/consumerreviews?StartItem=0&ItemsPerPage=10&SortOrder=MostHelpful\n\nA hypothetical response to a fetch call to this API that returns only two reviews (one DealerRater and one Cars.com) is shown below. Note that typical response payloads will likely be much larger, I just simplified it down to make it easier to digest in the documentation:
\n{\n \"PagingContext\": {\n \"StartItem\": 0,\n \"ItemsPerPage\": 10,\n \"TotalItems\": 2\n },\n \"Ratings\": [\n {\n \"Name\": \"Overall\",\n \"Label\": \"Overall\",\n \"Required\": true\n },\n {\n \"Name\": \"CustomerService\",\n \"Label\": \"Customer Service\",\n \"Required\": false\n },\n {\n \"Name\": \"BuyingProcess\",\n \"Label\": \"Buying Process\",\n \"Required\": false\n },\n {\n \"Name\": \"QualityOfWork\",\n \"Label\": \"Quality Of Work\",\n \"Required\": false\n },\n {\n \"Name\": \"Facilities\",\n \"Label\": \"Facilities\",\n \"Required\": false\n },\n {\n \"Name\": \"Friendliness\",\n \"Label\": \"Friendliness\",\n \"Required\": false\n },\n {\n \"Name\": \"Quality\",\n \"Label\": \"Quality Of Work\",\n \"Required\": false\n },\n {\n \"Name\": \"Pricing\",\n \"Label\": \"Price\",\n \"Required\": false\n }\n ],\n \"Employees\": [\n {\n \"Id\": 238423,\n \"Active\": true,\n \"Picture\": \"https:\\/\\/cdn-user.dealerrater.com\\/images\\/dealer\\/19361\\/employees\\/b55f5935c282.jpg\",\n \"FirstName\": \"John\",\n \"LastName\": \"Doe\",\n \"Position\": \"Sales\"\n }\n ],\n \"Rollups\": {\n \"Employees\": [\n {\n \"Id\": 238423,\n \"Scopes\": [\n {\n \"Scope\": \"Global\",\n \"ReviewCount\": 232,\n \"AverageRating\": 4.5\n }\n ]\n }\n ],\n \"Dealer\": [\n {\n \"Scope\": \"Global\",\n \"Recommend\": 95,\n \"ReviewCount\": 5231,\n \"AverageRating\": 4.6\n } \n ]\n },\n \"Reviews\": [ \n {\n \"Id\": 2821331,\n \"Type\": \"DealerRater\",\n \"Scope\": \"SalesUsed\",\n \"Recommend\": true,\n \"UserName\": \"Reviewer Two\",\n \"Title\": \"Title of the review\",\n \"Body\": \"Body of the review will go here\",\n \"Date\": \"2019-08-18T09:40:14Z\",\n \"Votes\": {\n \"Up\": 1,\n \"Down\": 0\n },\n \"Ratings\": {\n \"Average\": 5,\n \"Overall\": 5,\n \"Friendliness\": 5\n },\n \"EmployeeTags\": [\n {\n \"Id\": 238423\n }\n ],\n \"OtherEmployees\": \"Jane Doe\",\n \"Responses\": [\n {\n \"Body\": \"This is a public dealer response on this review.\",\n \"Date\": \"2019-08-18T09:40:14Z\",\n \"From\": \"Dealer\"\n },\n {\n \"Body\": \"This is a public consumer response on this review.\",\n \"Date\": \"2019-08-18T09:40:14Z\",\n \"From\": \"Consumer\"\n }\n ],\n \"LotShot\": [\n {\n \"PhotoUrl\": \"/images/lotshot/5939aa6f-7a4c-450b-80a1-c2c185958bd6.jpg\",\n \"ThumbnailUrl\": \"/images/lotshot/5939aa6f-7a4c-450b-80a1-c2c185958bd6-th.jpg\",\n \"Date\": \"2019-08-18T09:40:14Z\"\n }\n ]\n }\n ]\n}\n\nIn order to invoke this API, you will need an API key that is authorized to utilize this service. The API key should be passed in the x-api-key header as part of the request. No Oauth or JWT token will be required, to keep latencies down.
In the case of a successful fetch, you'll be given a 200 OK resopnse code and the response payload will have the data as defined in this API.
A 400 Bad Request will be returned if, and only if, you invoke this API passing in a Cars.com CCID for which we have no record.
There was an error with your JWT token.
\nThere was an error with your x-api-key API Gateway token.
\nYou have been throttled by our API Gateway. We are not intending to implement throttling on this endpoint, but if we detect 3rd parties fetching content at a rate that is causing service issues, we may need to implement some form of throttling. Unless otherwise noted, there will be no throttling for Cars.com or DealerRater consumers to this endpoint.
\nSomething unexpected happened while we were trying to fetch the reviews. If this occurs, it is critical that you log the x-correlation-id header in your logs so that we can do root cause analysis on our end and fix whatever went wrong. If this happens, please reach out to our development or product staff, passing along the relevant information (full set of filter and sort options, etc), as well as the returned x-correlation-id header for us to investigate.
We will be implementing very heavy caching on this API, and it will involve an eventual-consistency data model. Because the API takes several forms of filter and sort criteria (including paging values), we need to calculate responses for every permutation that is requested of the API itself. You can make the cache work better for you by keeping the total number of permutations of these values as low as possible; for example, instead of allowing the user to select between 10, 20, 30, 40, 50, 60, 70, 80, 90 or 100 result set sizes, set it statically at 20 - or pick a few that you deem most important.
\n","urlObject":{"protocol":"https","path":["review_v1","dealers","d","{{DealerId}}","consumerreviews"],"host":["{{ServicesHost}}"],"query":[{"disabled":true,"description":{"content":"Either \"true\" (only return Positive reviews), \"false\" (only return Negative reviews), or omitted, which will cause the API to return all reviews regardless of sentiment.
\n","type":"text/plain"},"key":"Recommend","value":"true"},{"disabled":true,"description":{"content":"The first review to fetch when paging.
\n","type":"text/plain"},"key":"StartItem","value":"0"},{"disabled":true,"description":{"content":"Maximum number of reviews to return per page.
\n","type":"text/plain"},"key":"ItemsPerPage","value":"10"},{"disabled":true,"description":{"content":"When rendering reviews on an employee profile page, you can pass the ID of the employee in here to filter reviews to just that employee.
\n","type":"text/plain"},"key":"EmployeeId","value":"48213"},{"disabled":true,"description":{"content":"One of the enumerated values outlined in the API definition.
\n","type":"text/plain"},"key":"SortOrder","value":"MostRecent"},{"disabled":true,"description":{"content":"If given, filter on the supplied Scope(s). You can list multiple scopes on the query line by having multiple Scope parameters, allowing you to filter on more than one value. If omitted, then reviews in all scopes are returned.
\n","type":"text/plain"},"key":"Scope","value":"SalesNew"}],"variable":[]}},"response":[],"_postman_id":"73397584-2f25-43d0-9997-c8765500592a"}],"id":"f921d3d6-f7db-4553-a967-44079ab8fd54","_postman_id":"f921d3d6-f7db-4553-a967-44079ab8fd54","description":""},{"name":"Review Entity","item":[{"name":"Review Responses","item":[{"name":"New Dealer Review Response","id":"facfe512-e020-4741-ad04-937ebc2d7dec","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"x-api-key","value":"{{ApiKey}}","description":"The API key you were issued by DealerRater, granting access through our API Gateway.
\n"},{"key":"Authorization","value":"Bearer {{AccessToken}}","description":"The access token granting permissions to invoke this API endpoint, with permissions as outlined in the specification above.
\n"},{"key":"Content-Type","value":"application/json","description":"Note that you MUST specify the Content-Type header as application/json or the server will not be able to parse your submission.
\n","type":"text"}],"body":{"mode":"raw","raw":"{\r\n \"Body\": \"Thank you for the kind words, we are so happy you had a great experience! If we can serve your needs at any point in the future, please don't hesitate to give us a call!\"\r\n}"},"url":"https://{{ServicesHost}}/review_v1/dealers/d/{{DealerId}}/reviews/{{ReviewId}}/responses","description":"This API should be invoked if you'd like to create a new response on an existing DealerRater Dealer Review. Responses are the sole mechanism a dealer has to communicate back to a consumer on a review that the consumer left - perhaps to thank them for a nice review, or to ask if there is anything they might do to assist in the case of a bad experience or negative review. For now, there will be a one response maximum per review. Attempting to create a new response on a review that already has a response will yield an error.
\nThe Dealer Response must include a Body property that is non-null and contains at least one, but not more than 25K (25,600) characters. It must also include a Private bool property that denotes if the response should be private or public facing, and a FromReviewer bool that denotes if the response is coming from the reviewer or the dealership.
In order to post a new response to the review service, you will need to provide a JWT access token in the Authorization header as an Authorization: Bearer [YOUR_TOKEN] value. The access token should have been generated using the Security API as described in this documentation with the DealerRater id of the dealer in the scope of the request, and the access token should not have expired. You must be granted the rvw_dr_write permission in order to invoke the API.
Here is a sample request body outlining how to create a new response on a review. Note that the ReviewId (and DealerId that owns the review) that stipulate which review is receiving the response, are included in the URI (in the case below, a made-up dealer ID of 2345 and review ID of 5678 are used).
\nPOST /review_v1/dealers/d/2345/reviews/5678/responses\n{\n \"Body\": \"Thank you for the kind words, we are so happy you had a great experience! If we can serve your needs at any point in the future, please don't hesitate to give us a call!\",\n \"FromReviewer\" : false,\n \"Private\" : false\n}\n\nYou can expect one of several response codes.
\nIn the event of a successful submission of a response to our platform, you can expect to receive a 201 Created HTTP response code.
\n{\n \"Response\": {\n \"Id\": 8859087,\n \"Body\": \"New review response\",\n \"Private\": false,\n \"FromReviewer\": false,\n \"DateEntered\": \"2025-11-12T14:55:16Z\",\n \"DateUpdated\": \"2025-11-12T14:55:16Z\"\n }\n}\n\nThe body of the response also includes a few extra properties, should you need them for whatever:
\nId: The surrogate key of the response.
Body: The response body, verbatim and echoed back to the caller (this will be identical to what you POSTed).
DateEntered: When the response was created (timestamp of this call, essentially).
DateUpdated: When the response was last updated (since this is a new response, it will be the same as DateEntered).
In the event of a malformed payload, if the server is unable to decipher what you have submitted, or if your submission does not for some means pass our validation rules (if the Body was not provided, or was too large), you will receive a 400 Bad Request response code. The response body will have some details as to what caused the 400 Bad Request error. Fix your submission and try again.
You are not authorized to invoke this endpoint. This might be that your API key and/or submitted JWT bearer token do not posses the required privileges to invoke this endpoint or that your JWT token is valid but expired. If you expect to have privileges to invoke this API, you'll need to verify that the required headers are present, have the correct name, and are being submitted per the requirements laid out in this specification.
\nWe were unable to find the given Review ID to add the response to.
\nSomething unexpected happened during the processing of your review submission. If this occurs, it is critical that you log the x-correlation-id header in your logs so that we can do root cause analysis on our end and fix whatever went wrong. If this happens, please reach out to our development or product staff, passing along the relevant information (full request body if you have it) as well as the returned x-correlation-id header for us to investigate.
The API key you were issued by DealerRater, grating access through our API Gateway.
\n"},{"key":"Authorization","value":"Bearer {{AccessToken}}","description":"The access token granting permissions to invoke this API endpoint, with permissions as outlined in the specification above.
\n"},{"key":"Content-Type","value":"application/json","description":"Note that you MUST specify the Content-Type header as application/json or the server will not be able to parse your submission.
\n","type":"text"}],"body":{"mode":"raw","raw":"{\n \"Body\": \"This is an update. Thank you for the kind words, we are so happy you had a great experience! If we can serve your needs at any point in the future, please don't hesitate to give us a call!\"\n}"},"url":"https://{{ServicesHost}}/review_v1/dealers/d/{{DealerId}}/reviews/{{ReviewId}}/responses/{{ResponseId}}","description":"This API should be invoked if you'd like to update an existing response on a DealerRater Dealer Review.
\nThe Dealer Response must include a Body property that is non-null and contains at least one, but not more than 25K (25,600) characters.
In order to update an existing response in the review service, you will need to provide a JWT access token in the Authorization header as an Authorization: Bearer [YOUR_TOKEN] value. The access token should have been generated using the Security API as described in this documentation with the DealerRater id of the dealer in the scope of the request, and the access token should not have expired. You must be granted the rvw_dr_write permission for the associated dealer Id in order to invoke the API.
Here is a sample request body outlining how to update an existing response on a review. Note that the ReviewId (and DealerId that owns the review) that stipulate which review is receiving the response, are included in the URI (in the case below, a made-up dealer ID of 23456 and review ID of 56789, and we are updating response ID 843281).
\nPUT /review_v1/dealers/d/23456/reviews/56789/responses/843281\n{\n \"Body\": \"Thank you for the kind words, we are so happy you had a great experience! If we can serve your needs at any point in the future, please don't hesitate to give us a call!\"\n}\n\nYou can expect one of several response codes.
\nIn the event of a successful submission of an updated response to our platform, you can expect to receive a 200 OK HTTP response code. In the body of the payload you'll find the submitted response echoed back to you, along with a few extra properties (same as those you get when creating a new response):
\n{\n \"Id\": 23589723,\n \"Body\": \"Thank you for the kind words, we are so happy you had a great experience! If we can serve your needs at any point in the future, please don't hesitate to give us a call!\",\n \"DateEntered\": \"2020-11-18T09:40:14Z\",\n \"DateUpdated\": \"2020-11-18T09:40:14Z\"\n}\n\nThe body of the response also includes a few extra properties, should you need them for whatever:
\nId: The surrogate key of the response.
Body: The response body, verbatim and echoed back to the caller (this will be identical to what you sent to the server).
DateEntered: When the response was originally created.
DateUpdated: This will be updated to the current time, as the response was changed.
In the event of a malformed payload, if the server is unable to decipher what you have submitted, or if your submission does not for some means pass our validation rules (if the Body was not provided, or was too large), you will receive a 400 Bad Request response code. The response body will have some details as to what caused the 400 Bad Request error. Fix your submission and try again.
You are not authorized to invoke this endpoint. This might be that your API key and/or submitted JWT bearer token do not posses the required privileges to invoke this endpoint or that your JWT token is valid but expired. If you expect to have privileges to invoke this API, you'll need to verify that the required headers are present, have the correct name, and are being submitted per the requirements laid out in this specification.
\nThe given response ID could not be found to be updated.
\nYou have been throttled by our API Gateway. The caller should implement a backoff algorithm, slow down, and try again.
\nSomething unexpected happened during the processing of your review submission. If this occurs, it is critical that you log the x-correlation-id header in your logs so that we can do root cause analysis on our end and fix whatever went wrong. If this happens, please reach out to our development or product staff, passing along the relevant information (full request body if you have it) as well as the returned x-correlation-id header for us to investigate.
The API key you were issued by DealerRater, grating access through our API Gateway.
\n"},{"key":"Authorization","value":"Bearer {{AccessToken}}","description":"The access token granting permissions to invoke this API endpoint, with permissions as outlined in the specification above.
\n"}],"url":"https://{{ServicesHost}}/review_v1/dealers/d/{{DealerId}}/reviews/{{ReviewId}}/responses","description":"This API should be invoked if you'd like to delete an existing response on a DealerRater Dealer Review.
\nIn order to delete an existing response in the review service, you will need to provide a JWT access token in the Authorization header as an Authorization: Bearer [YOUR_TOKEN] value. The access token should have been generated using the Security API as described in this documentation with the CCID of the dealer in the scope of the request, and the access token should not have expired. You must be granted the rvw_dr_write permission scoped to the dealer in order to invoke the API.
Here is a sample request body outlining how to delete an existing response on a review. Note that the ReviewId (and DealerId that owns the review), along with the ResponseId you are requesting to be deleted, are included in the URI .
\nDELETE /review_v1/dealers/d/23456/reviews/7890/responses/56789\n\nYou can expect one of several response codes.
\nIn the event of a successful deletion of a response in the system, you'll receive a 200 OK response. The response body itself will be empty.
\nYou are not authorized to invoke this endpoint. This might be that your API key and/or submitted JWT bearer token do not posses the required privileges to invoke this endpoint or that your JWT token is valid but expired. If you expect to have privileges to invoke this API, you'll need to verify that the required headers are present, have the correct name, and are being submitted per the requirements laid out in this specification.
\nThe given response ID could not be found to be deleted.
\nYou have been throttled by our API Gateway. The caller should implement a backoff algorithm, slow down, and try again.
\nSomething unexpected happened during the processing of your review submission. If this occurs, it is critical that you log the x-correlation-id header in your logs so that we can do root cause analysis on our end and fix whatever went wrong. If this happens, please reach out to our development or product staff, passing along the relevant information (full request body if you have it) as well as the returned x-correlation-id header for us to investigate.
This folder contains the APIs specific to DealerRater Dealer Reviews.
\n","_postman_id":"a64d13e8-9662-4317-82a8-3d0428b55d57"}],"id":"19526a79-8194-4d44-965a-864e71b90d8c","description":"This section contains the APIs to create and fetch reviews, APIs to add, update and delete review responses.
\n","_postman_id":"19526a79-8194-4d44-965a-864e71b90d8c"},{"name":"Vehicle Review APIs","item":[{"name":"Cars.com","item":[{"name":"Ratings Collection","item":[{"name":"Get Vehicle Ratings (GET)","id":"a2e7bca5-259e-4475-8d79-74ad01512238","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"description":"The API key you were issued by DealerRater, grating access through our API Gateway.
\n","key":"x-api-key","value":"{{ApiKey}}"},{"description":"The access token granting permissions to invoke this API endpoint, with permissions as outlined in the specification above.
\n","key":"Authorization","value":"Bearer {{AccessToken}}"}],"url":"https://{{ServicesHost}}/review_v1/vehicles/c/reviews/ratings","description":"This API can be used to fetch the ratings that are currently configured for use on Cars.com vehicle reviews (these are the individual 1-5 star categories such as Overall, Price, Interior Design, etc, that a consumer can rate a given vehicle on). We are planning on adjusting these over time to help improve our review conversion.
\nThe rating categories returned here are to be used for rendering your review collection form. All ratings are configured per-Scope (CurrentlyOwnIt, UsedToOwnIt and TestDroveIt). Each review that is submitted is required to have a Scope set on it (one of the three listed above) and we will be changing these over time. When rendering your review form, you will need to ensure that the appropriate ratings are shown depending on which Scope the user has selected.
\nEach rating that is returned will also provide information on labels (what you should place in your UI when collecting the rating), whether each category is a required entry or an optional entry, and the JSON key to use for each when submitting the data to the review collection API (that information is documented in the New Vehicle Review API).
\nDue to the more sensitive nature of this API compared to the consumer read-optimized database, you are required to submit a JWT token with the rvw_cars permission to successfully fetch reviews from this endpoint.
The API will deliver a single list of rating categories in the response, an array under the Ratings property. Each object in that array is of the same type, and is defined below.
Each object in the Ratings array will provide you with three properties: Name, Label and Required, such as the following:
{\n \"Name\": \"BuyingProcess\",\n \"Label\": \"Buying Process\",\n \"Required\": false\n}\nIn the above example, we have a single rating. When submitting this rating to the new review API, you should use BuyingProcess for the key; when showing this category to an end-user and collecting the information, you should request a rating for the label Buying Process; and finally, the rating is optional - so the consumer is not required to supply it.
Note that when rendering the ratings to the end-user on your review collection form, you will need to order them in some fashion. We would recommend that you do the following to increase conversion:
\nLabel alphabeticallyThis will ultimately be up to your individual User Experience staff, just note the API does not dictate any particular ordering. It will only tell you what ratings are supported, which are required, and how to submit them to our review collection endpoints.
\nScope: This is an optional query parameter that can be sent, and must be one of UsedToOwnIt, CurrentlyOwnIt or TestDroveIt. If omitted, the API will return the full rating configuration for all three scopes. If given, it will return only the configuration for the requested scope. When integrating with the API, you can either fetch the rating configuration and cache it in-browser while the user composes their review, switching ratings as necessary when the scope changes; or, you can invoke the API each time the user changes the scope, fetching only the ratings you need for that value.
\nA hypothetical response to a fetch call to this API that returns only one review is shown below. Note that typical response payloads will likely be much larger, I just simplified it down to make it easier to digest in the documentation:
\n{\n\"Scopes\": [\n {\n \"Scope\": \"TestDroveIt\",\n \"Ratings\": [\n {\n \"Name\": \"Overall\",\n \"Label\": \"Overall\",\n \"Required\": true\n },\n {\n \"Name\": \"Comfort\",\n \"Label\": \"Comfort\",\n \"Required\": false\n },\n {\n \"Name\": \"InteriorDesign\",\n \"Label\": \"Interior Design\",\n \"Required\": false\n },\n {\n \"Name\": \"Performance\",\n \"Label\": \"Performance\",\n \"Required\": false\n },\n {\n \"Name\": \"Price\",\n \"Label\": \"Price\",\n \"Required\": false\n },\n {\n \"Name\": \"ExteriorStyling\",\n \"Label\": \"Exterior Styling\",\n \"Required\": false\n },\n {\n \"Name\": \"Reliability\",\n \"Label\": \"Reliability\",\n \"Required\": false\n }\n ]\n },\n {\n \"Scope\": \"CurrentlyOwnIt\",\n \"Ratings\": [\n {\n \"Name\": \"Overall\",\n \"Label\": \"Overall\",\n \"Required\": true\n },\n {\n \"Name\": \"Comfort\",\n \"Label\": \"Comfort\",\n \"Required\": false\n },\n {\n \"Name\": \"InteriorDesign\",\n \"Label\": \"Interior Design\",\n \"Required\": false\n },\n {\n \"Name\": \"Performance\",\n \"Label\": \"Performance\",\n \"Required\": false\n },\n {\n \"Name\": \"Price\",\n \"Label\": \"Price\",\n \"Required\": false\n },\n {\n \"Name\": \"ExteriorStyling\",\n \"Label\": \"Exterior Styling\",\n \"Required\": false\n },\n {\n \"Name\": \"Reliability\",\n \"Label\": \"Reliability\",\n \"Required\": false\n }\n ]\n },\n {\n \"Scope\": \"UsedToOwnIt\",\n \"Ratings\": [\n {\n \"Name\": \"Overall\",\n \"Label\": \"Overall\",\n \"Required\": true\n },\n {\n \"Name\": \"Comfort\",\n \"Label\": \"Comfort\",\n \"Required\": false\n },\n {\n \"Name\": \"InteriorDesign\",\n \"Label\": \"Interior Design\",\n \"Required\": false\n },\n {\n \"Name\": \"Performance\",\n \"Label\": \"Performance\",\n \"Required\": false\n },\n {\n \"Name\": \"Price\",\n \"Label\": \"Price\",\n \"Required\": false\n },\n {\n \"Name\": \"ExteriorStyling\",\n \"Label\": \"Exterior Styling\",\n \"Required\": false\n },\n {\n \"Name\": \"Reliability\",\n \"Label\": \"Reliability\",\n \"Required\": false\n }\n ]\n }\n]\n}\nIn the case of a successful fetch, you'll be given a 200 OK resopnse code and the response payload will have the data as defined in this API.
A 400 Bad Request will be returned if there was a validation error. Please check the response payload to resolve the issue and try again.
There was an error with your JWT token.
\nThere was an error with your x-api-key API Gateway token.
\nYou have been throttled by our API Gateway. We are not intending to implement throttling on this endpoint, but if we detect 3rd parties fetching content at a rate that is causing service issues, we may need to implement some form of throttling. Unless otherwise noted, there will be no throttling for Cars.com or DealerRater consumers to this endpoint.
\nSomething unexpected happened while we were trying to fetch the reviews. If this occurs, it is critical that you log the x-correlation-id header in your logs so that we can do root cause analysis on our end and fix whatever went wrong. If this happens, please reach out to our development or product staff, passing along the relevant information (full set of filter and sort options, etc), as well as the returned x-correlation-id header for us to investigate.
This is an optional parameter. If provided, the API will return only the ratings applicable for the given Scope (UsedToOwnIt, CurrentlyOwnIt, or TestDroveIt). If omitted, the API will return the rating configuration for all three scopes.
\n","type":"text/plain"},"key":"Scope","value":"{{Scope}}"}],"variable":[]}},"response":[],"_postman_id":"a2e7bca5-259e-4475-8d79-74ad01512238"}],"id":"96b7245a-41c3-4a68-8eb3-bc41d016c9a8","description":"This folder has APIs related to fetching ratings specific to Cars.com vehicle reviews.
\n","_postman_id":"96b7245a-41c3-4a68-8eb3-bc41d016c9a8"},{"name":"Reviews Collection","item":[{"name":"Fetch Vehicle Reviews (GET)","id":"8b19fe89-1783-4bcf-af65-576ac869db7a","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"description":"The API key you were issued by DealerRater, grating access through our API Gateway.
\n","key":"x-api-key","value":"{{ApiKey}}"}],"url":"https://{{ServicesHost}}/review_v1/vehicles/c/{{VehicleId}}/consumerreviews?=","description":"This API should be your starting point if you are planning on implementing a high-capacity, high-traffic, web page on which you want to render vehicle review data.
\nThe API will deliver several major pieces of data in the response you'll need to understand with each and every request.
\nThe PagingContext is our standard data structure we use to inform consumers on total result set sizes for queries off this API (you can use it for rendering result set paging links, for example). The PagingContext is specific to anything you might filter on. You can use this object to determine how many pages are in your result set, for example. The StartItem and ItemsPerPage properties merely echo back the values you've passed in with your request, while the TotalItems property tells you how many total items are in this particular result set. To calculate the total number of pages, simply divide TotalItems by ItemsPerPage and round up.
We calculate rollups on a number of different dimensions per-vehicle. The Rollups section will be split into a single section that contains just the rollups itself, Vehicle. Before we can more fully understand the rollups, however, we need to provide a definition of a Scope.
The review platform includes the concept of a \"Scope\" that allows us to slice and dice reviews along at least one dimension. For vehicle reviews, we'll support TestDroveIt, CurrentlyOwnIt and UsedToOwnIt. There will always be one additional scope relevant to all reviews called Global.
You will only ever get one set of vehicle rollups per vehicle - and since you're loading by vehicle ID, you'll only get rollups for that one vehicle. We've encapsulated the rollup in an embedded Vehicle property (see the full response below). For vehicles, you will get rollups on the Global scope as well as per-rating rollups for each of the independent categories on which vehicles can be rated.
{\n \"Scope\": \"Global\",\n \"Recommend\": 94.4,\n \"ReviewCount\": 733,\n \"AverageRating\": 4.8,\n \"Ratings\": {\n \"Overall\": 4.8,\n \"Price\": 4.6,\n \"Comfort\": 4.9,\n \"InteriorDesign\": 4.8,\n \"Performance\": 4.8,\n \"ExteriorStyling\": 4.8,\n \"Reliability\": 4.8\n }\n}\nIn the example above, this hypothetical vehicle has a 94.4% recommendation rating over 733 reviews with a 4.8 average rating for all reviews for all time in all scopes.
\nAnd finally for the meat of the call, the reviews that matched the fetch itself.
\nA Cars.com vehicle review will be structured as follows:
\n{\n \"Id\": 3468137,\n \"Source\": \"Cars\",\n \"Scope\": \"CurrentlyOwnIt\",\n \"Recommend\": true,\n \"Title\": \"Great used truck!\",\n \"Body\": \"I bought it used to haul stuff occasionally. It ended up being a daily driver, which means 85 highway miles a day.\",\n \"Ratings\": {\n \"Average\": 4.7,\n \"Overall\": 4,\n \"Comfort\": 5,\n \"InteriorDesign\": 5,\n \"Performance\": 5,\n \"Price\": 5,\n \"ExteriorStyling\": 5,\n \"Reliability\": 4\n },\n \"UserName\": \"KCMike\",\n \"UserLocation\": \"Waltham, MA\",\n \"PurchasedNew\": false,\n \"PrimaryUse\":\"HavingFun\",\n \"Date\": \"2017-10-01T00:47:21\",\n \"Votes\": {\n \"Up\": 1,\n \"Down\": 0\n }\n}\nFairly simple. Each property maps to a question answered by the reviewer on form submission. To be clear:
\nId: Surrogate key for the review, required by other API endpoints.Source: This will be Cars for Cars.com reviews.Scope: The scope selected by the consumer (TestDroveIt, CurrentlyOwnIt or UsedToOwnIt).Recommend: true or false, based on if the reviewer recommends the vehicle.UserName: The name the reviewer wants to be known by.UserLocation: The location the reviewer indicated they live in.Title: Small one-sentence blurb to title the review.Body: The review body itself.PurchasedNew (optional): If true, the vehicle was purchased new, false used. If null, then the reviewer did not give an answer.PrimaryUse (optional): Optional field indicating how the user intends to use the vehicle. Options include Commuting, HavingFun, OffRoading, Towing, TransportingFamily, Work, SaveGas, JustGettingAround, and OutdoorSports.Date: The date to show for the review on the public website.Votes: Any up or down votes on the review from consumers.Ratings: Includes one entry for each of the ratings provided by the reviewer and an additional Average that is the calculated average of the individual ratings. Cars.com reviews can be rated on the following properties: Overall, Comfort, InteriorDesign, Performance, Price, ExteriorStyling and Reliability.This section lists off the various mechanisms by which you may request filtering of review content for Cars.com.
\nThe VehicleId is passed in as part of the URI itself. You will need to pass in the ID of the vehicle as part of the request.
FIXME: THIS SECTION IS TBD
\nIt is recommended for performance reasons that you include some form of paging on your reviews page. When requesting a particular page of results from the API, you'll need to pass StartItem (start index is zero and increments as whole integers) and ItemsPerPage (indicates the maximum number of reviews you'd want on any given result set). Here is an example that shows a paged result set, 10 reviews per page, requesting the 3rd page of 10 reviews:
/reviews_v1/vehicles/c/VEHICLEID/consumerreviews?StartItem=30&ItemsPerPage=10\nWe will support four sort criteria at launch. The default sort (when not requested) is outlined below. Each value may be passed in as the SortOrder query parameter.
SortOrder value is MostRecent. When sorting by Most Recent, the most recent reviews are returned first, with older reviews later.SortOrder value is HighestRated. When sorting by Highest Rated, we return the reviews with the highest average score first; for reviews with the same average score, a secondary sort by MostRecent is applied.SortOrder value is LowestRated. When sorting by Lowest Rated, we return the reviews with the lowest average score first; for reviews with the same average score, a secondary sort by MostRecent is applied.SortOrder value is MostHelpful. When sorting by Most Helpful, we return the reviews with the highest up-vote count first; for reviews with the same up-vote count, a secondary sort by MostRecent is applied.Requesting the most helpful reviews for vehicle ID VEHICLEID can be done like this (assuming a page count size of 10):
/reviews_v1/vehicles/c/VEHICLEID/consumerreviews?StartItem=30&ItemsPerPage=10&SortOrder=MostHelpful\nA hypothetical response to a fetch call to this API that returns only a single review is shown below. Note that typical response payloads will likely be much larger, I just simplified it down to make it easier to digest in the documentation:
\n{\n \"PagingContext\": {\n \"StartItem\": 0,\n \"ItemsPerPage\": 10,\n \"TotalItems\": 1\n },\n \"Rollups\": {\n \"Vehicle\": [\n {\n \"Scope\": \"Global\",\n \"Lifetime\": {\n \"Recommend\": 94.4,\n \"ReviewCount\": 733,\n \"AverageRating\": 4.8,\n \"Ratings\": {\n \"Overall\": 4.8,\n \"Price\": 4.6,\n \"Comfort\": 4.9,\n \"InteriorDesign\": 4.8,\n \"Performance\": 4.8,\n \"ExteriorStyling\": 4.8,\n \"Reliability\": 4.8\n }\n },\n \"Recent\": {\n \"Recommend\": 93.1,\n \"ReviewCount\": 492,\n \"AverageRating\": 4.7,\n \"Ratings\": {\n \"Overall\": 4.7,\n \"Price\": 4.5,\n \"Comfort\": 4.8,\n \"InteriorDesign\": 4.8,\n \"Performance\": 4.7,\n \"ExteriorStyling\": 4.8,\n \"Reliability\": 4.7\n }\n }\n }\n ]\n },\n \"ReviewTags\": [\n {\n \"Id\": \"AB3AD9837CEA78DA48B2AE4F31D3FAEC\",\n \"Name\": \"sporty\",\n \"Highlights\": [ \"sporty\" ] \n }\n ],\n \"Reviews\": [ \n {\n \"Id\": 3468137,\n \"Source\": \"Cars\",\n \"Scope\": \"CurrentlyOwnIt\",\n \"Recommend\": true,\n \"Title\": \"Great used truck!\",\n \"Body\": \"I bought it used to haul stuff occasionally. It ended up being a daily driver, which means 85 highway miles a day.\",\n \"Ratings\": {\n \"Average\": 4.7,\n \"Overall\": 4,\n \"Comfort\": 5,\n \"InteriorDesign\": 5,\n \"Performance\": 5,\n \"Price\": 5,\n \"ExteriorStyling\": 5,\n \"Reliability\": 4\n },\n \"UserName\": \"KCMike\",\n \"Date\": \"2017-10-01T00:47:21\",\n \"Votes\": {\n \"Up\": 1,\n \"Down\": 0\n }\n }\n ]\n}\nIn order to invoke this API, you will need an API key that is authorized to utilize this service. The API key should be passed in the x-api-key header as part of the request. No Oauth or JWT token will be required, to keep latencies down.
In the case of a successful fetch, you'll be given a 200 OK resopnse code and the response payload will have the data as defined in this API.
A 400 Bad Request will be returned if the server is unable to understand the request.
You either did not pass in the x-api-key header correctly or your API key is not authorized for the particular environment you are hitting. Double check the key and try again.
You have been throttled by our API Gateway. We are not intending to implement throttling on this endpoint, but if we detect 3rd parties fetching content at a rate that is causing service issues, we may need to implement some form of throttling. Unless otherwise noted, there will be no throttling for Cars.com or DealerRater consumers to this endpoint.
\nSomething unexpected happened while we were trying to fetch the reviews. If this occurs, it is critical that you log the x-correlation-id header in your logs so that we can do root cause analysis on our end and fix whatever went wrong. If this happens, please reach out to our development or product staff, passing along the relevant information (full set of filter and sort options, etc), as well as the returned `x-correlation-i set it statically at 20 - or pick a few that you deem most important.
If the user clicks on one of the review tags listed, pass the ID to only return reviews matching that tag. Omit to not filter on tags.
\n","type":"text/plain"},"key":"ReviewTag","value":"FBBAD9837CEA78DA48B3AE4F31D3FAEC"},{"disabled":true,"description":{"content":"The first review to fetch when paging.
\n","type":"text/plain"},"key":"StartItem","value":"0"},{"disabled":true,"description":{"content":"Maximum number of reviews to return per page.
\n","type":"text/plain"},"key":"ItemsPerPage","value":"10"},{"disabled":true,"description":{"content":"One of the enumerated values outlined in the API definition.
\n","type":"text/plain"},"key":"SortOrder","value":"MostRecent"},{"key":"","value":""}],"variable":[]}},"response":[],"_postman_id":"8b19fe89-1783-4bcf-af65-576ac869db7a"},{"name":"New Vehicle Review (POST)","id":"910fcd5f-0706-43ff-95d8-b3a6d6bbe2b8","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"description":"The API key you were issued by DealerRater, grating access through our API Gateway.
\n","key":"x-api-key","value":"{{ApiKey}}"},{"description":"The access token granting permissions to invoke this API endpoint, with permissions as outlined in the specification above.
\n","key":"Authorization","value":"Bearer {{AccessToken}}"},{"description":"Note that you MUST specify the Content-Type header as application/json or the server will not be able to parse your submission.
\n","key":"Content-Type","name":"Content-Type","type":"text","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"Device\": {\n \"Guid\": \"29e7feb9-2469-4d10-aaf8-64d53a80fd97\",\n \"IpAddress\": \"10.1.1.1\"\n },\n \"Vehicle\": {\n \"Id\": \"CarsMMY_36293525\",\n \"Year\": \"2018\",\n \"Make\": \"Ford\",\n \"Model\": \"F-150\",\n \"URL\": \"https://www.cars.com/research/ford-f150-2018/\"\n },\n \"EmailAddress\": \"foo@bar.com\",\n \"Scope\": \"TestDroveIt\",\n \"Ratings\": {\n \"Overall\": 5,\n \"Comfort\": 5,\n \"InteriorDesign\": 5,\n \"Performance\": 5,\n \"Price\": 5,\n \"ExteriorStyling\": 5,\n \"Reliability\": 5\n },\n \"Title\": \"Best truck\",\n \"Body\": \"Fell in love with that truck best truck I've seen, again , can't wait to test drive the new 2019 . I've always had fords\",\n \"PrimaryUse\": \"Commuting\",\n \"SourceCode\": \"SourceCode\",\n \"Recommend\": true,\n \"PurchasedNew\": true,\n \"UserName\": \"farlej2\",\n \"UserLocation\": \"Waltham, MA\"\n}\n"},"url":"https://{{ServicesHost}}/review_v1/vehicles/c/{{VehicleId}}/reviews","description":"This API should be invoked if you'd like to create a new Cars.com Vehicle Review. The API outlined below requires all the core Cars.com Vehicle Review properties, including outlining what is required and what is optional, as well as a bunch of extra data that is required by our moderation platform. All reviews submitted to this endpoint will go live immediately with ONE exception: if the review submitted here is detected to have profane content by our moderation algorithms, it will be held in reserve until such time as our moderation staff can look at it. Only at that point will the review either go live (be approved) or be taken down permanently (rejected).
\nIn order for us to accept a review submission, we require a minimal amount of data in order for our moderators to ensure that reviews are real, legitimate, experiences by consumers and not 3rd parties acting on paid behalf of dealers and other stakeholders.
\nThe first piece of data we need is tied to the device the consumer was using to write their review. There are two pieces of data our moderators really like to have, though neither of these is required. The first is called the Device GUID. We request that all submitters of content to our review service somehow tag devices with unique identifiers; in the case of browsers, it can be cookies; in the case of native apps, you can generate one on app install, etc. The second is the Reviewer IP Address. This is exactly as it sounds: the IP address from which the reviewer wrote the review (as close as we can get to their actual IP, even if it is just a NAT IP). If you only supply one (or neither) of these values, you risk that our moderation team will reject what might be a valid review, because it will look as though they are all written by the same person. The device information documented here looks like this in the request body of the POST call:
\"Device\": {\n \"Guid\": \"28e7feb9-2369-4d10-aaf8-64d53a80fd97\",\n \"IpAddress\": \"1.2.3.4\"\n}\n\nIf you're writing a vehicle review, we need to know what vehicle you are writing a review for. The full set of properties of the vehicle includes the name of the vehicle as well as the year, make and model. Note that the surrogate key is included on the URI for the review post, so that is the ID we interpret. You can feel free to pass in the same Id value here (as a property on the same level as year, make, model, etc) but it will be ignored. The vehicle information is identical to what our moderation platform expects, and looks like this:
\"Vehicle\": {\n \"Year\": \"2018\",\n \"Make\": \"Ford\",\n \"Model\": \"F-150\",\n \"URL\": \"https://www.cars.com/research/ford-f150-2018/\"\n}\n\nNote that the vehicle's surrogate key (the VehicleId) is actually included in the URI of the POST call itself.
All Cars.com reviews submitted to the review service must conform to the standard Cars.com review requirements model, including the following properties.
\nThis property is common across all review types in the system and is used for various internal aggregation algorithms for the purpose of scoping reviews of the same type. For the purposes of Cars.com Vehicle Reviews, you may pass in one of three values: TestDroveIt, CurrentlyOwnIt or UsedToOwnIt.
The main body of the review, with a required word count of 25. The word count validation conforms to the following algorithm: split the body of the review on whitespace and count the leftover tokens. If the token count is 25 or more, the validation will succeed. The body must also have no more than 2,000 words and no more than 4,000 characters. Any review submitted to our service that fails these checks will be rejected with a 400 Bad Request error.
\nThe consumer will need to rate the vehicle on a number of different rating categories as defined by the Ratings Collection endpoint. This endpoint is documented elsewhere in the collection and the URI, for reference, is:
\n/review_v1/vehicles/c/reviews/ratings\n\nWhat you will be required to do is fetch the rating definitions from this endpoint prior to rendering your review form. The rating categories (the 1-5 star fields the user can supply) are defined here. That API will tell you not only the labels to supply on your UI, but also how to submit the rating values as part of the review form to this service.
\nNote that the ratings are configured per-Scope; when creating a new Vehicle Review you must supply a Scope property whose value is CurrentlyOwnIt, UsedToOwnIt or TestDroveIt. The ratings the user should be presented with are those that are associated with the selected scope that you have retrieved from the ratings API (e.g., if the consumer selects TestDroveIt, the UI should show the ratings associated with TestDroveIt; if the user then changes to CurrentlyOwnIt, the ratings should then reflect the CurrentlyOwnIt configuration). Ratings with the same Name property value can have their rating selections retained when changing Scopes, if you so choose (some ratings may be shared between different scopes).
For the sake of example, assume that the ratings endpoint above returned the following two categories for the CurrentlyOwnIt scope:
{\n\"Ratings\": [\n {\n \"Name\": \"Overall\",\n \"Label\": \"Overall\",\n \"Required\": true\n },\n {\n \"Name\": \"InteriorDesign\",\n \"Label\": \"Interior Design\",\n \"Required\": false\n }\n]\n}\n\nYour user input form would need to request two 5-star entries, labelled in your UI as \"Overall\" and \"Interior Design\". The \"Overall\" category, as denoted above, is required - so the consumer should be required to supply a star rating for this category. Interior Design, being optional, can be omitted should the consumer choose not to supply it.
\nNote that you will need to sort these on your UI. While the ratings endpoint doesn't specifically stipulate a sort order, we are recommending you do the following:
\nLabel alphabeticallyWhen submitting the ratings from the UI to our service, you will need to package up the ratings supplied by the consumer into a ratings object. The property names for each rating are supplied by the Name attribute above. If the consumer supplied a 5-star Overall rating and a 4-star Interior Design rating, you would submit it as:
\"Ratings\": { \n \"Overall\": 5,\n \"InteriorDesign\": 4\n}\n\nHere is an example of another reviewer that supplied only the Overall rating:
\n\"Ratings\": { \n \"Overall\": 2\n}\n\nThe API will also ignore any ratings you supply with a null or 0 value, should that make your life easier. The example above, where the consumer just supplied a 2-star Overall rating, can also be submitted as:
\"Ratings\": { \n \"Overall\": 2,\n \"InteriorDesign\": null\n}\n\nNote: Failure to submit a star rating for all required categories will result in a 400 Bad Request error and your review submission will be rejected.
\nThis section outlines the other properties, what they mean, and which are required or optional.
\ntrue or false label.null, please reach out to our business deparatment to see if they'd like a particular value here.Commuting, HavingFun, OffRoading, Towing, TransportingFamily, Work, SaveGas, JustGettingAround or OutdoorSports.In order to post a new review to the review service, you will need to provide a JWT access token in the Authorization header as an Authorization: Bearer [YOUR_TOKEN] value. You must be granted the rvw_cars permission in order to invoke the API.
Here is a sample request body outlining all the properties outlined in the overview section in one sample review submission:
\n{\n \"Device\": {\n \"Guid\": \"28e7feb9-2469-4d10-aaf8-64d53a80fd77\",\n \"IpAddress\": \"10.1.1.1\"\n },\n \"Vehicle\": {\n \"Id\": \"CarsMMY_36293525\",\n \"Year\": \"2018\",\n \"Make\": \"Ford\",\n \"Model\": \"F-150\",\n \"URL\": \"https://www.cars.com/research/ford-f150-2018/\"\n },\n \"EmailAddress\": \"foo@bar.com\",\n \"Scope\": \"TestDroveIt\",\n \"Ratings\": {\n \"Overall\": 5,\n \"Comfort\": 5,\n \"InteriorDesign\": 5,\n \"Performance\": 5,\n \"Price\": 5,\n \"ExteriorStyling\": 5,\n \"Reliability\": 5\n },\n \"Body\": \"Fell in love with that truck best truck I've seen , can't wait to test drive the new 2019 . I've always had fords\",\n \"PrimaryUse\": \"Commuting\",\n \"SourceCode\": \"SourceCode\",\n \"Recommend\": true,\n \"PurchasedNew\": true,\n \"UserName\": \"farlej2\",\n \"UserLocation\": \"Waltham, MA\"\n}\n\nYou can expect one of several response codes.
\nIn the event of a successful submission of a review to our platform, you can expect to receive a 201 Created HTTP response code. In the body of the payload you'll find the submitted review echoed back to you, along with a new Id property identifying the surrogate key of the new review in the review platform. Please note that due to how our moderation system works, if we detect that the text contains profane content, it might be scrubbed out during our moderation process (e.g., the review title, text, and other user-entered data could be returned at a later date in a slightly different format to remove the profane content). An example response would look something like this for the request body posted above:
{\n \"Id\": 129281,\n \"Scope\": \"TestDroveIt\",\n \"Ratings\": {\n \"Overall\": 5,\n \"Comfort\": 5,\n \"InteriorDesign\": 5,\n \"Performance\": 5,\n \"Price\": 5,\n \"ExteriorStyling\": 5,\n \"Reliability\": 5\n },\n \"Body\": \"Fell in love with that truck best truck I've seen , can't wait to test drive the new 2019 . I've always had fords\",\n \"PrimaryUse\": \"Commuting\",\n \"SourceCode\": \"SourceCode\",\n \"Recommend\": true,\n \"PurchasedNew\": true,\n \"UserName\": \"farlej2\",\n \"UserLocation\": \"Waltham, MA\"\n}\n\nIn the event of a malformed payload, if the server is unable to decipher what you have submitted, or if there is a validation error, you will receive a 400 Bad Request response code. The response body will have some details as to what caused the 400 Bad Request error. Fix your submission and try again.
\nYou are not authorized to invoke this endpoint. This might be that your API key and/or submitted JWT bearer token do not posses the required privileges to invoke this endpoint or that your JWT token is valid but expired or was from a different DealerRater environment. If you expect to have privileges to invoke this API, you'll need to verify that the required headers are present, have the correct name, and are being submitted per the requirements laid out in this specification.
\nYou have been throttled by our API Gateway.
\nSomething unexpected happened during the processing of your review submission. If this occurs, it is critical that you log the x-correlation-id header in your logs so that we can do root cause analysis on our end and fix whatever went wrong. If this happens, please reach out to our development or product staff, passing along the relevant information (full request body if you have it) as well as the returned x-correlation-id header for us to investigate.
This folder contains the APIs specific to Cars.com Vehicle Reviews.
\n","_postman_id":"9e685caa-8f3c-4de3-acff-94a3fd5d4b93"}],"id":"9b440eeb-9bb1-4d24-a8de-d8b80f18ce1c","description":"This section contains the APIs to create, fetch and otherwise manage vehicle reviews.
\n","_postman_id":"9b440eeb-9bb1-4d24-a8de-d8b80f18ce1c"},{"name":"Dealer APIs","item":[{"name":"Makes","item":[{"name":"Get Makes","id":"aa9e6b3c-38ba-4ba4-a4f4-50fa39dfd462","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"key":"x-api-key","value":"{{ApiKey}}","description":"The API key you were issued by DealerRater, grating access through our API Gateway.
\n","type":"text"}],"url":"https://{{ServicesHost}}/dealer_v1/makes/","description":"This API will return you all makes.
\nThe service will respond with 200 status and JSON object along with our standard headers. Sample response body follows:
\n{\n\"Makes\": [\n {\n \"Id\": 1,\n \"Name\": \"Acura\",\n \"Category\": [\"Popular\"]\n },\n {\n \"Id\": 2,\n \"Name\": \"Alfa Romeo\",\n \"Category\": [\"Other\"]\n }\n]\n}\n\nThe Id of the make
The Name of the make
The Category of the make - for now the value is either Popular or Other and can be used to display the makes in separate groups if needed
The API key you were issued by DealerRater, grating access through our API Gateway.
\n","type":"text"}],"url":"https://{{ServicesHost}}/dealer_v1/makes/15/models","description":"This API will return all models for a given MakeId.
\nThe service will respond with 200 status and JSON object along with our standard headers. Sample response body follows:
\n{\n \"Models\": [\n {\n \"Id\": 541,\n \"Name\": \"Aerostar\"\n },\n {\n \"Id\": 542,\n \"Name\": \"Aspire\"\n }]\n}\n\nThe Id of the Model
The Name of the Model
The API key you were issued by DealerRater, grating access through our API Gateway.
\n","type":"text"}],"url":"https://{{ServicesHost}}/dealer_v1/makes/15/models/543","description":"This API will return a single model for a given make Id and model id.
\nThe service will respond with 200 status and JSON object along with our standard headers. Sample response body follows:
\n{\n \"Model\": [\n {\n \"Id\": 541,\n \"Name\": \"Aerostar\"\n }]\n}\n\nThe Id of the Model
The Name of the Model
This folder contains the APIs specific to Makes.
\n","_postman_id":"6b62ab82-dbdf-4331-99c7-93389fd099d7"},{"name":"Dealers","item":[{"name":"Makes","item":[{"name":"Get Makes for Dealer Id","id":"113811a6-3a04-4180-9d53-2566ef8f0cb0","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"key":"x-api-key","value":"{{ApiKey}}","description":"The API key you were issued by DealerRater, grating access through our API Gateway.
\n","type":"text"}],"url":"https://{{ServicesHost}}/dealer_v1/dealers/{{DealerId}}/makes/","description":"This API will return you all makes a dealer sells.
\nThe service will respond with 200 status and JSON object along with our standard headers. Sample response body follows:
\n{\n \"Makes\": [\n {\n \"Id\": 15,\n \"Name\": \"Ford\",\n \"DisplayCategory\": \"Popular\"\n },\n {\n \"Id\": 28,\n \"Name\": \"Lincoln\",\n \"DisplayCategory\": \"Popular\"\n }\n ]\n}\n\nThe Id of the make
The Name of the make
The DisplayCategory of the make - the value is either Popular or Other and can be used to display the makes in separate groups if needed
This API will return data about the given single DealerRater dealer Id.
\nThe API will deliver dealer metadata in the response..
\nA single dealer will be structured as follows:
\n{\n \"Id\": 4184,\n \"Name\": \"Delaware Cadillac\",\n \"Address\": \"1606 Pennsylvania Avenue\",\n \"City\": \"Wilmington\",\n \"State\": \"DE\",\n \"Country\": \"US\",\n \"PostalCode\": \"19806\",\n \"WebAddress\": \"https://www.delawarecadillac.com/\",\n \"SalesPhone\": \"3026563100\",\n \"ServicePhone\": \"3026563100\",\n \"PartsPhone\": \"3026563100\",\n \"AboutUs\": \"Delaware Cadillac - and our Dealership Group - AutoTeam Delaware - was originally founded in 1916, and we have been family-owned since 1982. We are a Founding Member of The Delaware Better Business Bureau. We consistently receive some of the highest customer satisfaction ratings for both Cadillac sales & service. \\r\\n\\r\\nWe are a 2020 Cadillac National Dealer of the Year Award Winner, as well as 2020 & 2021 Cadillac National Master Dealer Award Winner.\\r\\n\\r\\nAt Delaware Cadillac, we offer every Cadillac service and amenity for both Sales and Service!\\r\\n\\r\\nVehicle Purchase Amenities: A Personalized Sales Experience ** Great Vehicle Pricing ** One of the Largest Selection in the greater Philadelphia area of New, Certified, & Pre-Owned Cadillac Vehicles to choose from - In Stock, In Transit, and In Build Status ** \\\"Start My Deal\\\" online Payment Tool - Customize Your Payments including Tax, Checkout with PayPal ** Finance & Credit Experts ** Home Delivery Vehicle Purchases ** Clean, Safe, & Healthy Showroom Visits ** We Support Our Local Community!!!\\r\\n\\r\\nService Visit Amenities: Complimentary Vehicle Wash with Every Service Visit ** Available Valet Pick-Up and Drop-Off ** Free Loaner Vehicles ** Free Shuttle Service ** Free Multi-Point Vehicle Inspections ** Our own Cadillac Roadside Assistance Technician to go out to clients in our Local Area ** Competitive Service, Parts, & Accessory Pricing ** Free In-Dealership Amenities for Wait Services ** Clean, Safe, & Healthy Service Visits ** Cadillac Factory Trained Technicians ** Genuine Cadillac Parts & Accessories!\",\n \"Latitude\": 39.7541,\n \"Longitude\": -75.5642\n }\n\nEach property maps to a property of the dealer as stored by DealerRater.
\nThe DealerRater Id of the dealer
The Name of the dealer
The dealer's Address, City, State, Country and PostalCode
The dealer's WebAddress
The dealer's SalesPhone, ServicePhone and PartsPhone
The dealer's AboutUs blurb
The dealer's Latitude and Longitude
Any Awards the dealer has won - each award has a Type, Year and ImageUrl, and they are sorted by most award type (DOTY then CSA, then by year, then by national, regional, national brand, state brand). Additional award properties for DOTY awards include -Category, Country, State , For
This section lists off the various mechanisms by which you may request filtering of dealers.
\nThe DealerId is passed in as part of the URI.
The Source is passed in as a query string parameter. Options are Cars and DealerRater - if no source is provided, DealerRater is the default. If Cars is the source, all matching DealerRater dealer ids are found and the response includes only the sorted Awards object, not any of the other Dealer metadata.
A hypothetical response to a fetch call to this API that returns a dealer is shown below.
\n {\n \"Id\": 2259,\n \"Name\": \"Bozard Ford Lincoln\",\n \"Address\": \"540 Outlet Mall Blvd\",\n \"City\": \"St. Augustine\",\n \"State\": \"FL\",\n \"Country\": \"US\",\n \"PostalCode\": \"32084\",\n \"WebAddress\": \"http://www.bozardford.com/\",\n \"SalesPhone\": \"9048225561\",\n \"ServicePhone\": \"9045923346\",\n \"PartsPhone\": \"9045923347\",\n \"AboutUs\": \"Bozard Ford Lincoln has gained national recognition as the recipient of numerous awards. Our dealership is a repeat Triple Crown Award winner! This is Ford Motor Company's most prestigious honor which is awarded to only the top 1% of Ford dealers in the nation. A Triple Crown Award recipient must receive Ford's President's Award, be a Top 100 Volume Dealer, and meet the Partner’s in Quality criteria. We have also been a recipient of DealerRater's Ford and Lincoln Dealer of the Year Award for the entire state of Florida based on customer reviews concerning friendliness, quality of service, and overall customer satisfaction.\\r\\n \",\n \"Latitude\": 29.9279584,\n \"Longitude\": -81.4147714,\n \"Awards\": [\n {\n \"Type\": \"DOTY\",\n \"Year\": 2024,\n \"ImageUrl\": \"https://d2fdfggt01p5tp.cloudfront.net/doty/2024/US/seal2/national/28.png\",\n \"Category\": \"BrandNational\",\n \"Country\": \"US\",\n \"For\": \"Lincoln\"\n },\n {\n \"Type\": \"CSA\",\n \"Year\": 2024,\n \"ImageUrl\": \"https://local.dealerrater.com/ncdn/s/0.0.0/Graphics/locales/en-US/csa/2024-seal.png\"\n },\n] \n }\n\nIn the case of a successful fetch, you'll be given a 200 OK resopnse code and the response payload will have the data as defined in this API..
The given dealer ID does not exist or the dealer has been deleted.
\nYou have been throttled by our API Gateway. We are not intending to implement throttling on this endpoint, but if we detect 3rd parties fetching content at a rate that is causing service issues, we may need to implement some form of throttling. Unless otherwise noted, there will be no throttling for Cars.com or DealerRater consumers to this endpoint.
\nSomething unexpected happened while we were trying to fetch the reviews. If this occurs, it is critical that you log the x-correlation-id header in your logs so that we can do root cause analysis on our end and fix whatever went wrong. If this happens, please reach out to our development or product staff, passing along the relevant information (full set of filter and sort options, etc), as well as the returned x-correlation-id header for us to investigate.
This API will return data about the given set of DealerRater dealer Ids.
\nThe API will deliver dealer metadata in the response.
\nThe PagingContext is our standard data structure we use to inform consumers on total result set sizes for queries off this API (you can use it for rendering result set paging links, for example). The PagingContext can be used to determine how many pages are in your result set, for example. The StartItem and ItemsPerPage properties merely echo back the values you've passed in with your request, while the TotalItems property tells you how many total items are in this particular result set. To calculate the total number of pages, simply divide TotalItems by ItemsPerPage and round up.
The Awards array contains a consolidated list of awards in the correct business sort order for all dealer ids provided. It is only returned in the response when the optional ConsolidateAwards param is included and set to true.
The Dealers array contains one dealer per item in the array, and each item has an assortment of properties, each described below.
A single dealer will be structured as follows:
\n{\n \"Id\": 4184,\n \"Name\": \"Delaware Cadillac\",\n \"Address\": \"1606 Pennsylvania Avenue\",\n \"City\": \"Wilmington\",\n \"State\": \"DE\",\n \"Country\": \"US\",\n \"PostalCode\": \"19806\",\n \"WebAddress\": \"https://www.delawarecadillac.com/\",\n \"SalesPhone\": \"3026563100\",\n \"ServicePhone\": \"3026563100\",\n \"PartsPhone\": \"3026563100\",\n \"AboutUs\": \"Delaware Cadillac - and our Dealership Group - AutoTeam Delaware - was originally founded in 1916, and we have been family-owned since 1982. We are a Founding Member of The Delaware Better Business Bureau. We consistently receive some of the highest customer satisfaction ratings for both Cadillac sales & service. \\r\\n\\r\\nWe are a 2020 Cadillac National Dealer of the Year Award Winner, as well as 2020 & 2021 Cadillac National Master Dealer Award Winner.\\r\\n\\r\\nAt Delaware Cadillac, we offer every Cadillac service and amenity for both Sales and Service!\\r\\n\\r\\nVehicle Purchase Amenities: A Personalized Sales Experience ** Great Vehicle Pricing ** One of the Largest Selection in the greater Philadelphia area of New, Certified, & Pre-Owned Cadillac Vehicles to choose from - In Stock, In Transit, and In Build Status ** \\\"Start My Deal\\\" online Payment Tool - Customize Your Payments including Tax, Checkout with PayPal ** Finance & Credit Experts ** Home Delivery Vehicle Purchases ** Clean, Safe, & Healthy Showroom Visits ** We Support Our Local Community!!!\\r\\n\\r\\nService Visit Amenities: Complimentary Vehicle Wash with Every Service Visit ** Available Valet Pick-Up and Drop-Off ** Free Loaner Vehicles ** Free Shuttle Service ** Free Multi-Point Vehicle Inspections ** Our own Cadillac Roadside Assistance Technician to go out to clients in our Local Area ** Competitive Service, Parts, & Accessory Pricing ** Free In-Dealership Amenities for Wait Services ** Clean, Safe, & Healthy Service Visits ** Cadillac Factory Trained Technicians ** Genuine Cadillac Parts & Accessories!\",\n \"Latitude\": 39.7541,\n \"Longitude\": -75.5642,\n \"Awards\": [\n {\n \"Type\": \"DOTY\",\n \"Year\": 2024,\n \"ImageUrl\": \"https://d2fdfggt01p5tp.cloudfront.net/doty/2024/US/seal2/national/28.png\",\n \"Category\": \"BrandNational\",\n \"Country\": \"US\",\n \"For\": \"Lincoln\"\n },\n {\n \"Type\": \"CSA\",\n \"Year\": 2024,\n \"ImageUrl\": \"https://local.dealerrater.com/ncdn/s/0.0.0/Graphics/locales/en-US/csa/2024-seal.png\"\n },\n]\n\n }\n\nEach property maps to a property of the dealer as stored by DealerRater.
\nThe DealerRater Id of the dealer
The Name of the dealer
The OemNameof the dealer (some dealers provide an alternate OEM specified name in this field)
The dealer's Address, City, State, Country and PostalCode
The dealer's WebAddress
The dealer's SalesPhone, ServicePhone and PartsPhone
The dealer's AboutUs blurb
The dealer's Latitude and Longitude
Any Awards the dealer has won - each award has a Type, Year and ImageUrl, and they are sorted by most award type (DOTY then CSA, then by year, then by national, regional, national brand, state brand). Additional award properties for DOTY awards include -Category, Country, State , For
This section lists off the various mechanisms by which you may request filtering of dealers.
\nThe DealerId is passed in one or multiple query parameters, as ?i={DealerId}. If you want to return multiple dealers just string them together for example - ?i={DealerId}&i={Dealer2Id}
To filter dealers by name, the Name is passed in as a query parameter as ?name=NameToSearch. You must provide at least 2 characters to search dealers by name.
To filter dealers by postal code, the PostalCode is passed in as a query parameter as ?PostalCode=12345. You must provide at least 5 characters to search dealers by postal code, and results will include dealers that have an exact match on the postal code provided.
To filter dealers by phone number, the PhoneNumber is passed in as a query parameter as ?PhoneNumber=12345. Results will include dealers where the Sales, Service or Parts phone contains the numbers provided in the param.
To filter dealers by address, the Address is passed in as a query parameter as ?Address=Main Street. Results will include dealers where the address contains the string provided in the param.
To return a consolidated list of awards in the correct sort order for multiple passed in dealer ids,ConsolidateAwardsis passed in as a query parameter as ?ConsolidateAwards=true.
It is recommended for performance reasons that you include some form of paging on your reviews page. When requesting a particular page of results from the API, you'll need to pass StartItem (start index is zero and increments as whole integers) and ItemsPerPage (indicates the maximum number of dealers you'd want on any given result set). Here is an example that shows a paged result set, 2 dealers per page, requesting the 2nd page of 2 dealers:
/dealer_v1/dealers?StartItem=2&ItemsPerPage=2&i=2259&i=4185&i=4184&i=2\n\nA hypothetical response to a fetch call to this API that returns only two dealers is shown below.
\n \"PagingContext\": {\n \"StartItem\": 0,\n \"ItemsPerPage\": 200,\n \"TotalItems\": 2\n },\n \"Dealers\": [\n {\n \"Id\": 2259,\n \"Name\": \"Bozard Ford Lincoln\",\n \"Address\": \"540 Outlet Mall Blvd\",\n \"City\": \"St. Augustine\",\n \"State\": \"FL\",\n \"Country\": \"US\",\n \"PostalCode\": \"32084\",\n \"WebAddress\": \"http://www.bozardford.com/\",\n \"SalesPhone\": \"9048225561\",\n \"ServicePhone\": \"9045923346\",\n \"PartsPhone\": \"9045923347\",\n \"AboutUs\": \"Bozard Ford Lincoln has gained national recognition as the recipient of numerous awards. Our dealership is a repeat Triple Crown Award winner! This is Ford Motor Company's most prestigious honor which is awarded to only the top 1% of Ford dealers in the nation. A Triple Crown Award recipient must receive Ford's President's Award, be a Top 100 Volume Dealer, and meet the Partner’s in Quality criteria. We have also been a recipient of DealerRater's Ford and Lincoln Dealer of the Year Award for the entire state of Florida based on customer reviews concerning friendliness, quality of service, and overall customer satisfaction.\\r\\n \",\n \"Latitude\": 29.9279584,\n \"Longitude\": -81.4147714\n },\n {\n \"Id\": 4184,\n \"Name\": \"Delaware Cadillac\",\n \"Address\": \"1606 Pennsylvania Avenue\",\n \"City\": \"Wilmington\",\n \"State\": \"DE\",\n \"Country\": \"US\",\n \"PostalCode\": \"19806\",\n \"WebAddress\": \"https://www.delawarecadillac.com/\",\n \"SalesPhone\": \"3026563100\",\n \"ServicePhone\": \"3026563100\",\n \"PartsPhone\": \"3026563100\",\n \"AboutUs\": \"Delaware Cadillac - and our Dealership Group - AutoTeam Delaware - was originally founded in 1916, and we have been family-owned since 1982. We are a Founding Member of The Delaware Better Business Bureau. We consistently receive some of the highest customer satisfaction ratings for both Cadillac sales & service. \\r\\n\\r\\nWe are a 2020 Cadillac National Dealer of the Year Award Winner, as well as 2020 & 2021 Cadillac National Master Dealer Award Winner.\\r\\n\\r\\nAt Delaware Cadillac, we offer every Cadillac service and amenity for both Sales and Service!\\r\\n\\r\\nVehicle Purchase Amenities: A Personalized Sales Experience ** Great Vehicle Pricing ** One of the Largest Selection in the greater Philadelphia area of New, Certified, & Pre-Owned Cadillac Vehicles to choose from - In Stock, In Transit, and In Build Status ** \\\"Start My Deal\\\" online Payment Tool - Customize Your Payments including Tax, Checkout with PayPal ** Finance & Credit Experts ** Home Delivery Vehicle Purchases ** Clean, Safe, & Healthy Showroom Visits ** We Support Our Local Community!!!\\r\\n\\r\\nService Visit Amenities: Complimentary Vehicle Wash with Every Service Visit ** Available Valet Pick-Up and Drop-Off ** Free Loaner Vehicles ** Free Shuttle Service ** Free Multi-Point Vehicle Inspections ** Our own Cadillac Roadside Assistance Technician to go out to clients in our Local Area ** Competitive Service, Parts, & Accessory Pricing ** Free In-Dealership Amenities for Wait Services ** Clean, Safe, & Healthy Service Visits ** Cadillac Factory Trained Technicians ** Genuine Cadillac Parts & Accessories!\",\n \"Latitude\": 39.7541,\n \"Longitude\": -75.5642\n }\n ]\n}\n\nIn the case of a successful fetch, you'll be given a 200 OK resopnse code and the response payload will have the data as defined in this API..
You have been throttled by our API Gateway. We are not intending to implement throttling on this endpoint, but if we detect 3rd parties fetching content at a rate that is causing service issues, we may need to implement some form of throttling. Unless otherwise noted, there will be no throttling for Cars.com or DealerRater consumers to this endpoint.
\nSomething unexpected happened while we were trying to fetch the reviews. If this occurs, it is critical that you log the x-correlation-id header in your logs so that we can do root cause analysis on our end and fix whatever went wrong. If this happens, please reach out to our development or product staff, passing along the relevant information (full set of filter and sort options, etc), as well as the returned x-correlation-id header for us to investigate.
This folder contains the APIs specific to Dealers.
\n","_postman_id":"7457a35d-0e4c-4e6b-9621-f164b9c99a9d"}],"id":"fd8f1e1a-582c-4385-b828-45f045aeb6b1","description":"This API is to be used as a central clearinghouse for all operations related to the following business entities:
\n