The public JSON Collect API allows you to collect feedback about reviews and submit new reviews and questions.
Feedback about helpfulness or inappropriate content is used to improve the API results and can be submitted to the location specified by feedback_url individually for each review in the JSON Display API results.
Feedback is posted as application/x-www-form-urlencoded data containing the feedback type and (optional) comment. For example:
POST /path/from/feedback/url HTTP/1.1
Host: domain.from.feedback.url
Content-Type: application/x-www-form-urlencoded
Content-Length: 28
type=up&comment=text+comment
| type | up - Review was helpful.down - Review was not helpful.reset - Remove previous votes (must be combined with voter_id)bad - Review has incorrect or inappropriate content |
Required |
| voter_id | Unique visitor id to allow changing or removing previous votes. | |
| comment | Feedback of type bad may be accompanied by an optional comment. |
The following API location allow you to submit reviews and questions using your client ID and associated public API key:
https://reviews.testfreaks.com/api/
Submission takes the form of a POST request with an application/json body with the following parameters:
| client_id | Your client name/ID string. |
| api_key | Your public API key. Note: the public API key is not sensitive information, and can safely be used where anyone could see it. |
| product_id | The product identifier used when retrieving reviews/questions from the related APIs using key. Limited to 255 characters. |
| product_site_id | The product family identifier, used when retrieving reviews/questions from the related APIs using url_key. Limited to 255 characters. |
| product_name | The name of the product. Limited to 255 characters. |
| product_url | The product page URL. |
| author | Author’s name or alias as published with the review/question. Limited to 255 characters. |
| author_email | Author’s email address. |
| author_ip | Author’s IP address. |
| images | List of images. See Submitting Images |
POST https://reviews.testfreaks.com/api/reviews
Content-Type: application/json
{
"client_id": "your.client.id",
"api_key": "API_KEY",
"product_id": "p123-01",
"product_site_id": "p123",
"product_name": "Product Name",
"product_url": "https://retailer.example/product/p123?variant=01",
"author": "Author Name or Alias",
"author_ip": "1.2.3.4",
"author_email": "reviewer@example.com",
"score": 5,
"content": "Review content",
"pros": ["Pro 1", "Pro 2"],
"cons": ["Con 1", "Con 2"],
"images": []
}
| score | Numeric value between 1 and 5. | Required |
| pros | List of positives limited to 2000 characters each. | |
| cons | List of negatives limited to 2000 characters each. | |
| title | Not displayed by default but available on the API level. Limited to 255 characters. | |
| content | The review content limited to 60000 characters. |
POST https://reviews.testfreaks.com/api/questions
Content-Type: application/json
{
"client_id": "your.client.id",
"api_key": "API_KEY",
"product_id": "p123-01",
"product_site_id": "p123",
"product_name": "Product Name",
"product_url": "https://retailer.example/product/p123?variant=01",
"author": "Author Name or Alias",
"author_ip": "1.2.3.4",
"author_email": "reviewer@example.com",
"question": "Question",
"details": "Details",
"mail_answer": "true",
"images": []
}
See Submitting images for details on how to upload and attach images to a review.
| question | The main question title or abstract, limited to 255 characters. | Required |
| mail_answer | Flag for the user wanting to be contacted by email when the question is answered. Valid values are “true” or “false”. | Required |
| details | Additional details about the question, limited to 60000 characters. |
The API will respond with code 201 on successful submissions and return a JSON body with the posted data.
Missing or incorrect client_id or api_key will result in a 403 response. Missing required fields will result in a 406 response with a JSON body listing the invalid fields.
Reviews and questions can be configured with custom questions for display or internal use.
The answers can be submitted along with a review/question by adding the custom_questions field to the JSON body. For example:
"custom_questions": {
"example_score": 4,
"example_text": "Custom text answer",
"example_select_size": "small",
"example_select_skin": ["dry", "sensitive"]
}
The fields used within custom_questions match the question IDs configured for the client.
The values match the question type (score, text, select) and, in the case of select questions, the pre-defined option ID(s).
Reviews and questions can be submitted along with one or more images by uploading images to a separate API and including the results in the review/question submission.
First upload each image to the images API as multipart/form-data. For example using curl:
curl -F client_id=your.client.id -F api_key=PUBLIC_API_KEY -F file=@example.jpg
https://images.testfreaks.com/uploader
The JSON response from the uploader contains a set of image attributes in the following format:
{
"token": "0144cb49b0b35b9ff49a3f362bf6069a",
"format": "jpeg",
"width": 800,
"height": 600
}
After uploading the images, add the results from the uploader to the images parameter during review/question
submission. For example:
{
"images": [
{
"token": "0144cb49b0b35b9ff49a3f362bf6069a",
"format": "jpeg",
"width": 800,
"height": 600
}
]
}