The Reviews API returns your reviews, similar to the public JSON Display API, but also including non-published reviews and data.
Lists reviews matching the request parameters and provides a next page link if the result spans multiple pages.
limit
, how many reviews per page, default 100, maximum 1000
client_id
, if you have access to multiple clients with your api key
updated_after
(optional) set to YYYY-MM-DD
or YYYY-MM-DDTHH:MM:SSZ
(ISO 8601) to filter reviews
on updated timestamp. For example, 2021-10-01T13:00:00Z
created_after
(optional) set to YYYY-MM-DD
or YYYY-MM-DDTHH:MM:SSZ
(ISO-8601) to filter reviews
on created timestamp. For example, 2021-10-01T13:00:00Z
order_id
(optional) for filtering reviews on a specific Order ID
customer_id
(optional) for filtering reviews on a specific Customer ID
after
, used for pagination
See below, and see the separate description of fields.
If .links.next
is set, additional pages are available by following the link.
If .errors
is set, it’s a list of errors.
$ curl -u sk_token: https://api.testfreaks.com/v1/reviews?client_id=example.com
{
"data": [
{
"id": "e63b2ad38dd9ada0",
"type": "customer",
"author": "John D",
"score": 4,
"score_max": 5,
"date": "2021-11-22",
"extract": "Great product",
"pros": [
"pro1",
"pro2"
],
"cons": [],
"lang": "en",
"verified_buyer": true,
"votes_up": 0,
"votes_down": 0,
"product": "Product name",
"responses": [],
"images": [
{
"token": "43b1c28cea4f74e57701edf25ad4b671",
"format": "jpeg",
"width": 3840,
"height": 2160,
"icon": "<url>",
"icon_width": 100,
"icon_height": 100,
"medium": "<url>",
"medium_width": 1600,
"medium_height": 900,
"large": "<url>",
"large_width": 3840,
"large_height": 2160
}
],
"properties": {},
"family_ids": [
"P001"
],
"product_ids": [
"P001-02-BLK"
],
"order_id": "O123",
"customer_id": "C001",
"updated_at": "2021-11-22T06:38:04Z",
"accepted": true,
"accepted_at": "2021-11-22T08:31:46Z",
"verified_email": true,
"author_email": "john.doe@example.com",
"portal_url": "https://reviews.testfreaks.com/portal/reviews/e63b2ad38dd9ada0?client_id=your.client.id"
}
],
"links": {
"next": "https://api.testfreaks.com/v1/reviews?after=123123429"
}
}
In order to match the data format for POST/PUT, pros and cons are returned as lists instead of as combined texts as in the public JSON Display API.
Images contain additional fields as provided by the image API.
images.token | Image token |
images.format | Image format string |
images.width | Original image width |
images.height | Original image height |
Returns a single review based on its review ID.
Uses the same format as list reviews above except that it only returns a single object.
$ curl -u sk_token: https://api.testfreaks.com/v1/reviews/e63b2ad38dd9ada0?client_id=example.com
Creates a new review from the data in the JSON request body.
client_id
, if you have access to multiple clients with your api key
Set the Content-Type to application/json
and post review data using the following structure:
{
"review": {
"external_id": "R001",
"order": {
"id": "O123",
"customer": {
"id": "C001",
"name": "John Doe",
"email": "john.doe@example.com"
},
"item": {
"id": "P001-02-BLK",
"family_id": "P001"
}
},
"author": "John D",
"score": 4,
"date": "2022-10-01",
"extract": "Review content",
"pros": ["pro1", "pro2"],
"cons": ["con1"],
"images": [
{
"token": "43b1c28cea4f74e57701edf25ad4b671",
"format": "jpeg",
"width": 3840,
"height": 2160
}
],
"custom_questions": {
"fit": "small"
},
"accepted": true
}
}
external_id
(optional) can be used to provide a pre-existing review ID. Specifying an external_id
that already exist will update that review rather than creating a new review.
order
specifies the order details (including customer and product information) as per the v1/orders API but limited to a single order item.
author
is the public author name.
score
is the review score 1-5.
date
(optional) is the review date for importing pre-existing reviews.
extract
(optional) is the review content, limited to 60000 characters.
pros
and cons
(optional) are the individual positives/negatives. Limited to 2000 characters each.
images
(optional) is a list of image objects where each object is the result from uploading an image to the image API.
custom_questions
(optional) is a collection of question names and answer values, depending on what has been setup for the client_id
.
accepted
(optional) overrides the manual moderation process. true
marks the review as approved. false
marks the review as rejected. null
resets the moderation status to the default for a new review, allowing the system to decide how to handle moderation.
Returns the posted review data or a list of errors if the request was unsuccessful. See the response format for the review listing above.
Updates a single review based on its review ID.
Uses the same JSON body as in the POST above.
Deletes a review based on its review ID.